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:

1. How user and session differ between implementation modes.
2. 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="
    }
  ]
}

For the full API reference see here.

HTTP Response Codes

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).