Reporting Engagement

Request from: 

In the US:
server-side: https://dy-api.com/v2/collect/user/engagement
client-side: https://direct-collect.dy-api.com/v2/collect/user/engagement (supports CORS)

In the EU:
server-side:  https://dy-api.eu/v2/collect/user/engagement
client-side: https://direct-collect.dy-api.eu/v2/collect/user/engagement

See also – API Reference: Reporting Engagement

What's the difference between engagement and events?

Engagement is when a user interacts 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, and so on. Anything that's important for your business.

Both can be set as the Primary Metric for running campaigns. For more information, see Extra reading: Using clicks and events in campaigns.

Types of engagement

• CLICK: A user clicked on a displayed variation of a custom API campaign or the widget of a recommendation campaign, for example, the arrows or pagination. To report the click you need to pass us the unique decisionId value, as returned from the call to choose. When you are reporting engagement for multiple-variation campaigns you need to pass the id of the variation clicked. You can report CLICK engagements for control variations of recommendation campaigns, using the decisionId. 
  The variation ID is returned as part of the response to the choose request.
• IMP: Similar to CLICK, but reports impressions. 
• 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 that 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.
• SLOT_IMP: Similar to SLOT_CLICK, but reports impressions. 

Request format

If you are using Experience APIs and site personalization together, you use IDs managed by Dynamic Yield. In API-only mode, you pass self-managed identifiers.

In the following code snippets, note:

• How user and session 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"
  },
  "context": { "device": {"ip": "54.100.200.255" }},
  "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="
    }
  ]
}
  

See the full API reference for more information.

HTTP Response Codes

Extra reading: Using clicks and 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 (for example, 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, see Campaigns Overview.