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.

Get Started    

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

CodeMeaning
204Request succeeded. No body is returned
400Error parsing request
401Invalid or missing API key
403Access denied for a valid API key
405Wrong HTTP method (not POST, in this case)
422Request body did not match schema
429Too many requests received
451Wrong key type was used (server-side key used from client-side or client-side key used from server-side)
500Unspecified 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.
PropertyDescriptionType
dyTypeMust 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 negativeValue is float, currency is a string
productIdSKU as in the feedString
quantityProduct quantity added, should be non-negativeNumber
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).

PropertyDescriptionType
dyTypeMust 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 negativeValue is float, currency is a string
productIdSKU as in the feedString
quantityProduct quantity removed, should be non negativeNumber
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).

PropertyDescriptionType
dyTypeMust 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.
PropertyDescriptionType
dyTypeMust 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.
cartThe products purchasedArray 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.

PropertyDescriptionType
dyTypeMust be "add-to-wishlist-v1"String
productIdSKU as in the feedString

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.
PropertyDescriptionType
dyTypeMust be "login-v1"String
hashedEmail (optional)SHA-256 encoding of the lowercase email, if the email is knownString
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.

PropertyDescriptionType
dyTypeMust be "newsletter-subscription-v1"String
hashedEmailSHA-256 encoding of the lowercase emailString

Video Watch

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

PropertyDescriptionType
dyTypeMust be “video-watch-v1″String
itemIdMandatory 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 actionBoolean,
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
progressPercentOnly 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.

PropertyDescriptionType
dyTypeMust be "keyword-search-v1″String
keywordsThe search string, as isString

Updated about a month 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.