Engagement vs. Events
Engagement is a user interaction directly with a campaign variation - typically a click on a banner or a product in a recommendations widget.
In contrast, events are other significant user actions such as purchases, logins, making a deposit, watching a video, etc. - anything that's important for your business.
Both can be set as the Primary Metric for running campaigns - see the section below for more on this topic.
Types of Engagement
1. CLICK: A user clicked on a displayed variation of a Custom API Campaign. To report the click you need to pass us the unique decisionId
value, as returned from the call to choose.
2. SLOT_CLICK: For Recommendations Campaigns, it is important to let us know exactly which product was clicked on within the recommendations widget. This enables us to deliver in-depth analytics for recommendations which go beyond the campaign level, to the granularity of specific categories, products, strategies and more. Each product returned by choose
comes with a unique slotId
identifier, which is what you need to pass in the request.
Request Format
Depending on the implementation mode that you chose, the arguments passed to user
and session
differ. In API-Only Mode, you pass self-managed identifiers, while in Web Mode you'll use Dynamic Yield-managed IDs. For a refresher, see this guide.
In the snippets below, note:
- How
user
andsession
differ between implementation modes. - Typically, you only report a single click in a given call. The endpoint does support batches, which we're using here just to show the two types of engagement:
CLICK
for custom campaigns,SLOT_CLICK
for recommendations.
POST https://dy-api.com/v2/collect/user/engagement
DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c
Content-Type: application/json
{
"user": {
"id": "yaexono4ohphania"
},
"session": {
"custom": "iquahngaishe2koh"
},
"engagements": [
{
"type": "CLICK",
"decisionId": "aGVsbG8KhAc"
},
{
"type": "SLOT_CLICK",
"slotId": "aGVsbG93b3JsZAo="
}
]
}
POST https://dy-api.com/v2/collect/user/engagement
DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c
Content-Type: application/json
{
"user": {
"dyid": "16798430146043",
"dyid_server": "16798430146043"
},
"session": {
"dy": "a2719b4d6c470383f1bf3"
},
"engagements": [
{
"type": "CLICK",
"decisionId": "aGVsbG8KhAc"
},
{
"type": "SLOT_CLICK",
"slotId": "aGVsbG93b3JsZAo="
}
]
}
For the full API reference see here.
HTTP Response Codes
204 | Request succeeded. No body is returned |
---|---|
400 | Error parsing request |
401 | Invalid or missing API key |
403 | Access denied for a valid API key |
405 | Wrong HTTP method (not POST, in this case) |
422 | Request body did not match schema |
429 | Too many requests received |
451 | Wrong key type was used (server-side key used from client-side or client-side key used from server-side) |
500 | Unspecified internal error |
Extra Reading: The Usage of Clicks & Events in Campaigns
Campaigns can be set up so that their primary metric is the click engagement itself, if you wish to optimize by CTR (Click Through Rate). Alternatively, the metric could be any event along the user's journey, whether it typically takes a very short time or weeks for a user to trigger that desired event.
When the campaign's metric is an event, the creator of the campaign should also decide whether there must be explicit user engagement with the campaign variation (e.g. a click on a special offer is needed so that a purchase down funnel would be attributed to that offer variation). By default, it is enough that the variation was served by the API. This setting is named the Attribution Window in the Admin UI.
Of course, there's quite a lot that goes into setting up campaigns correctly: measuring the right metrics, setting the right attribution settings, and more. To learn more, read up on this topic in our Knowledge Base (login required).


Available attribution settings when creating an API campaign
Updated about a month ago
Further Reading
API Reference: Reporting Engagement |