Dynamic Yield Developer Documentation

Browse Dynamic Yield's latest developer documentation including API references, articles, and sample code for optimizing, personalizing, and creating consistent digital customer experiences across touchpoints.

TRY FOR FREE

Reporting Engagement

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

:notebook-with-decorative-cover+: API Reference: Reporting Engagement

Engagement vs. Events

Engagement is 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 that click you need to pass us with 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's you'll 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, please 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"
  },
  "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 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 hit 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 3 months ago



Reporting Engagement


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

:notebook-with-decorative-cover+: API Reference: Reporting Engagement

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.