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 Events

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

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

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

Events are used for tracking meaningful user interactions (e.g. purchase, add to cart, form completion, rating a product, or anything you want), and have many purposes:

  • Use for Behavioral targeting in campaigns.
  • Build audience groups, either long or short-term.
  • Set as the primary or secondary metrics in campaigns.
  • Events are also a data source for our recommendations engine, both for 'crowd-sourced' strategies such as Most Popular and Bought Together, and for personalized strategies and the Affinity Profile.

Events are stored in the Unified Customer Profile, from which you can later fetch them.

Types of Events

Events are broadly divided into two kinds:

Predefined Events

These events have a standard schema for their properties, and the properties passed with that event are used by our backend for various purposes. Let's dive right in with an example of reporting the predefined Add to Cart event:

curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "session": { "custom": "iquahngaishe2koh" },
      "events": [
        {
          "name": "Add to Cart",
          "properties": {
            "dyType": "add-to-cart-v1",
            "value": 39.95,
            "currency": "GBP",
            "productId": "item-34454ga",
            "quantity": 1
          }
        }
      ]
    }'
curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": {
        "dyid": "-4350463893986789401",
        "dyid_server": "-4350463893986789401"
      },
      "session": { "dy": "ohyr6v42l9zd4bpinnvp7urjjx9lrssw" },
      "events": [
        {
          "name": "Add to Cart",
          "properties": {
            "dyType": "add-to-cart-v1",
            "value": 39.95,
            "currency": "GBP",
            "productId": "item-34454ga",
            "quantity": 1
          }
        }
      ]
    }'

There are several things to note:

  1. You can batch multiple events together, and thus, events is always an array. This can be used for batching events from the client-side (but don't hold 'em in your belly for too long) or reporting events en-masse from your server.

  2. Each event has a required name, and an optional properties object. The name is used for display purposes. It does not designate whether this is a predefined event or its schema.

  3. The type (aka scheme name) of a predefined event is set in properties.dyType - see below for the full list of types. All attributes, either required by the schema or custom, are also included within the properties object.

  4. value can actually be passed with any event, including custom events, if the event has a monetary value. Without the optional currency argument, the value is taken to be in your site's currency, as defined in the site settings. You can, however, specify a different currency code, and the value would then be converted into the site's currency. It is a float number in the format of dollars[.cents], or its equivalent in other currencies.

The predefined "add-to-cart-v1" type in the example above requires two mandatory properties:

  • productId which must exactly match an SKU in the product feed.
  • quantity of the added product.

🚧

Good Housekeeping

Two things to keep care of:

1. Ensure you don't have ever-so-slightly differing variations on the SKU format between your feed, the events you report, and the context of pageviews you report. While SKUs may look deceptively simple, there are sometimes prefixes and suffixes which are only used in specific parts of your system. Typically, the component which generates the product feed is a whole other service, possibly written in a different language, from the code that reports client events.

2. It's good practice to use a single meaningful display name for each predefined type.
For a purchase event with the purchase-v1 schema, you may decide on either "Purchase", or any synonym, a translation of that term, or whatever term makes sense in your use case. However, stick to that single term in order not to confuse users of the Admin UI.

Events Identifying a Customer Across Channels

Some predefined events also serve to associate between the given User ID and a Customer ID. A User ID is unique to a device and may represent an anonymous user. It is the primary identifier in API endpoints. On the other hand, the optional Customer ID is a fixed identifier for a person that is the same across channels (web apps, mobile apps, e-mail) and usually available only for registered users. In this way, multiple devices can be linked together across devices.

The Customer ID (or CUID for short) can be any unique string, however, we recommend using the customer's email address as the unique identifier. This enables the email personalization features. Email addresses are, in almost all cases, not passed as plain-text. Rather, you should lower-case the email string and then hash it in SHA256 format. The lower-case step helps to ensure consistency between all identifying events for the same user reported from multiple sources, and with any first-party data that you upload. Note that hashed email addresses are then further encrypted when stored in our servers.

Dynamic Yield does not in any way mandate that you pass a Customer ID. However, if you decide to use identifying events (see list below), passing the Customer ID is required in some, and optional in others.

Here is an example for a Login event. With this event type, passing a hashed email is optional. Without it, the event demarcates a login which might be a primary metric for some campaign but is not tying the user ID with any customer ID.

curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "sessionId": "iquahngaishe2koh",
      "events": [
        {
          "name": "Login",
          "properties": {
            "dyType": "login-v1",
            "hashedEmail": "43e62d636651bc44edcd528a510d57ce69126cd875c..."
          }
        }
      ]
    }'

The above-encoded example for '"hashedEmail"' has been trimmed. It is the beginning of the full SHA256 hash for the string "[email protected]" (after converting it to lower-case first).

Custom Events

Here's where you get to report any event that doesn't carry a meaning for Dynamic Yield, but does have one for your business.

A custom event:

  • Must have a name for display, but does not have a dyType.
  • Can have a monetary value, with or without the optional currency designation.
  • Can have no extra properties, or multiple ones - strings, numbers, and boolean values. Note that we don't support nested properties when creating targeting rules over custom events.

Here's a simple example:

curl --request POST \
  --url https://dy-api.com/v2/collect/user/event \
  --header 'content-type: application/json' \
  --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
  --data '{
      "user": { "id": "yaexono4ohphania" },
      "sessionId": "iquahngaishe2koh",
      "events": [
        {
          "name": "Filled Post-Purchase Survey",
          "properties": {
            "customerRole": "VP of Staplers",
            "experienceRating": 4,
            "likesSpecialOffers": true
          }
        }
      ]
    }'

HTTP Response Codes

Code

Meaning

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

List of Predefined Events

Add to Cart

Required for eCommerce sites

Notes:

  • Please ensure the productId matches an SKU in the product feed.
  • Optionally, you may also pass the full updated cart with the newly added product to ensure the cart state as known to Dynamic Yield is fully in sync with your system. This is mainly needed for triggered email and push notifications.

Property

Description

Type

dyType

Must be "add-to-cart-v1"

String

value
and optional currency

Add to Cart events should always have the total value of the added product. Value should be non negative

Value is float, currency is a string

productId

SKU as in the feed

String

quantity

Product quantity added, should be non-negative

Number

cart (optional)

New cart state, including newly added item.

Array of objects.
Properties in each object:

  • productId - string
  • quantity - number
  • itemPrice - float in dollars.cents format
{
  name: "Add to Cart",
  properties: {
    dyType: "add-to-cart-v1",
    value: 198.00,
    productId: "p-tv78615a",
    quantity: 2,
    cart: [
      {
        productId: "p-cr91275g",
        quantity: 1,
        itemPrice: 49.95
      },
      {
        productId: "p-tv78615a",
        quantity: 2,
        itemPrice: 99.00,
      }
    ]
  }
}

Remove from Cart

The Remove from Cart event has the same schema as adding to cart (see above), except for its dyType property value. Unlike Add to Cart, it is not mandatory to implement this event unless you're using features which rely on Dynamic Yield holding the most up-to-date cart state (currently only triggered emails and push notifications).

Property

Description

Type

dyType

Must be "remove-from-cart-v1"

String

value
and optional currency

Remove from Cart events should always have the total value of the removed product. Value should be non negative

Value is float, currency is a string

productId

SKU as in the feed

String

quantity

Product quantity removed, should be non negative

Number

cart (optional)

New cart state, after the item is removed.

Array of objects.
Properties in each object:

  • productId - string
  • quantity - number
  • itemPrice - float in dollars.cents format

Synchronize Cart

This optional event can be fired on any change to the cart which does not fall under adding/removing a specific product from cart. Like Remove from Cart, this event is only needed for specific optional features (see above).

Property

Description

Type

dyType

Must be "sync-cart-v1"

String

cart (optional)

New cart state, including newly added item.

Array of objects.
Properties in each object:

  • productId - string
  • quantity - number
  • itemPrice - float in dollars.cents format

Purchase

Required for eCommerce sites

Notes:

  • Please ensure the productId property of each product matches an SKU in the product feed.
  • In this event, unlike adding/removing from cart, the cart parameter is mandatory and describes all products purchased, rather than the new cart state post-purchase (which is usually empty...).
  • The value parameter should be the total value of the cart purchased.
  • The uniqueTransactionId property is optional but recommended, for de-duping any duplicate events over the same purchase.

Property

Description

Type

dyType

Must be "purchase-v1"

String

value
and optional currency

Purchase events should always have the total value of the whole cart.

Value is float, currency is a string

uniqueTransactionId (optional)

If you pass this value, Dynamic Yield will ensure only one purchase is recorded per that transaction ID, even if duplicate events are reported.

String, 64 characters maximum.

cart

The products purchased

Array of objects.
Properties in each object:

  • productId - string
  • quantity - number
  • itemPrice - float in dollars.cents format
{
  name: "Purchase",
  properties: {
    dyType: "purchase-v1",
    value: 349.80,
    cart: [
      {
        productId: "p-tv78615a",
        quantity: 1,
        itemPrice: 249.90,
      },
      {
        productId: "p-cr91275g",
        quantity: 2,
        itemPrice: 49.95
      }
    ]
  }
}

Add to Wish List

Optional. Use if end-users can add items to a wish list, and you wish to track this behavior.

Property

Description

Type

dyType

Must be "add-to-wishlist-v1"

String

productId

SKU as in the feed

String

Login

Optionally identifying a customer

Use this event type to report a login by an existing registered user. For a new account sign up, use the Sign Up event instead.

Please make sure to read the section on Events Identifying a Customer Across Channels above. This event can be used with or without passing any registered Customer ID (CUID). That CUID may either be a hashed email or any custom type.

You have a few choices of what to include when sending this event:

  1. Report the event without any extra identifier to only track the action of the login itself, or -
  2. Report the event with a hashed email, enabling the usage of email features (and onboarding of first-party data whose primary key is typically hashed email), or -
  3. Report the event with a non-email CUID type. In this case, you may decide to explicitly specify the type by also setting the cuidType property. For example, pass "crmId" to designate identifiers created internally in your CRM.
    If cuidType is not set, a default type named “id” is used.

Property

Description

Type

dyType

Must be "login-v1"

String

hashedEmail (optional)

SHA-256 encoding of the lowercase email, if the email is known

String

cuidType (optional)
cuid (optional)

Instead of a hashed email, you may pass a custom type name into cuidType, and the actual ID in cuid

If only cuid is set, the type is set by default to "id"

String

{           
  "name": "Login",           
  "properties": {
    "dyType": "login-v1",
    "hashedEmail": "43e62d636651bc44edcd528a510d57ce69126cd875c..."           
  }
}
{           
  "name": "Login",           
  "properties": {
    "dyType": "login-v1",
    "cuidType": "crmAccountId",
    "cuid": "u7761034"
  }
}

Sign Up

Optionally identifying a customer

Report this event when a user has completed the sign-up process and has now become a registered customer. Optionally, you can also pass a hashed email or another Customer ID type to associate the user ID with that registered customer ID.
Usage of this event is the same as the Login Event above, with the dyType property being "signup-v1".

Newsletter Subscription

This event is identifying a customer

Report this event to track subscriptions (regardless of whether the user has an account) and associate the anonymous user ID with the hashed email entered by the user. This event does not accept custom Customer ID types and its main use is for enabling personalized email features.

Property

Description

Type

dyType

Must be "newsletter-subscription-v1"

String

hashedEmail

SHA-256 encoding of the lowercase email

String

Video Watch

Report this event to track a video watch in media sites and applications.

Property

Description

Type

dyType

Must be “video-watch-v1″

String

itemId

Mandatory string ID matching an identified present in the Content Feed (more details in the Knowledge Base)

String

autoPlay (optional)

Indicates if video was played automatically or because of an explicit user action

Boolean,
False by default

progress (optional)

One of the following values:

  • VIDEO_STARTED (default): The video has started playing. This does not indicate whether it was watched in full
  • PREROLL_FINISHED: The pre-roll was watched in full
    VIDEO_FINISHED: The content was watched in full
    VIDEO_PROGRESS: If the client can periodically report fine-grained progress as a percentage, use this value in conjunction with progressPercent

String

progressPercent

Only relevant if progress mode is “VIDEO_PROGRESS”

Number

{           
  "name": "Video Pre-roll Ended",           
  "properties": {
    "dyType": "video-watch-v1",
    "itemId":v-g67811a-people-watching-got-finale",
    "autoplay": true,
    "progress": "PREROLL_FINISHED"      
  }
}

Keyword Search

The user has run a free-style keyword search.

Property

Description

Type

dyType

Must be "keyword-search-v1″

String

keywords

The search string, as is

String

Updated 3 months ago



Reporting Events


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

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

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

Suggested Edits are limited on API Reference Pages

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