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 and custom events.

Predefined Events

These events have a standard schema for their properties, and the properties passed with the 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" },
      "context": { "device": {"ip": "54.100.200.255" }},
      "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 a given User ID to 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 is usually available only for registered users. In this way, multiple channels 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 the list below), passing the Customer ID is required in some events, and optional in others.

Here is an example for a Login event. With this event type, passing a hashed email is mandatory. Without it, the event demarcates a login which might be a primary metric for some campaign but does not tie the user ID to 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",
      "context": { "device": {"ip": "54.100.200.255" }},
      "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 zero or more extra properties - 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",
      "context": { "device": {"ip": "54.100.200.255" }},
      "events": [
        {
          "name": "Filled Post-Purchase Survey",
          "properties": {
            "customerRole": "VP of Staplers",
            "experienceRating": 4,
            "likesSpecialOffers": true
          }
        }
      ]
    }'

HTTP Response Codes

List of Predefined Events

Add to Cart

Notes:

• Ensure that 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 that 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.

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

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

Purchase

Notes:

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

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

Login

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.

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

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

Sign Up

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

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.

Video Watch

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

{           
  "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.