Events are used to track meaningful user interactions (such as purchase, add to cart, form completion, or rating a product) for behavioral targeting, reporting, and recommendations. To send event data to Dynamic Yield, implement a short snippet on the client-side, similar to Google Analytics events (for firing events on the server-side, learn more about Experience APIs).
There are some events – especially the common generic events, such as purchase or login – that should be implemented based on a predefined schema (see list), but you can also fire any custom event.
Note: On e-commerce sites, Purchase and Add to Cart events are mandatory. However, we recommend that you implement all other predefined events that are relevant to your site, as they will enable more use cases and improve the visitor profile.
Predefined event schemas
The user has added a product to the cart. This is a required event for e-commerce sites.
Parameters
- name: Human-readable name, not used to identify an event type.
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “add-to-cart-v1″ | String |
value | The total monetary value of the event | Float (dollars.cents). Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
currency Optional, but required for multi-currency sites |
The currency that is used for the value | String List of supported currencies |
productId | The SKU exactly as it appears in the product feed | String |
quantity | The total number of items that were added to cart | Number |
size Optional |
The size of the item (such as L, M, S, or any other label sizing method) | String |
cart Optional, but recommended |
The cart current state, including the last added item. Cart Properties: |
|
productId: SKU exactly as it appears in the product feed |
String |
|
quantity | Number | |
itemPrice | Number Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
|
size: Optional | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Add to Cart",
properties: {
dyType: "add-to-cart-v1",
value: 118.26,
currency: "any supported currency code",
productId: "item-34454",
quantity: 2,
size: "XL",
cart: [{
productId: "sku-4324-bg",
quantity: 2,
itemPrice: 12.34,
},
{
productId: "item-34454",
quantity: 2,
itemPrice: 59.13
}
]
}
});
For the Experience API format, see Add to Cart. The user has added a product to their Wishlist.
Parameters
- name: Human-readable name, not used to identify an event type.
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “add-to-wishlist-v1” | String |
productId | The product SKU | String |
size |
optional string | String |
JavaScript Example (site personalization/script)
DY.API("event", {
name: "Add to Wishlist",
properties: {
dyType: "add-to-wishlist-v1",
productId: "item-34454",
size: "XL"
}
});
For the Experience API format, see Add to Wishlist.The user has changed an attribute of the displayed product (e.g. color, fit).
Parameters
- name: Human-readable name, not used to identify an event type.
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “change-attr-v1” | String |
attributeType | Color, Size, Brand, Fit, Author, Keyword, Category… | String |
attributeValue | The new value | String |
Note: the attribute type and value should match the product feed. The currently displayed product is inferred from the in-page context.
JavaScript example (site personalization/script)
DY.API("event", {
name: "Change Attribute",
properties: {
dyType: "change-attr-v1",
attributeType: "Color",
attributeValue: "Navy Blue"
}
});
The user has filtered the product list by a specific field value.
Parameters
- name: Human-readable name, not used to identify an event type.
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “filter-items-v1” | String |
filterType | Name of filter (Color, Size, Brand, Fit, Author, Keyword, Category…).
Must correspond with a product property present in the Product Feed |
String |
filterNumericValue | Specify a value for this property OR for filterStringValue, but not both. This affects how segmentation conditions are run. | Number |
filterStringValue | Specify a value for this property OR for filterNumericValue, but not both. This affects how segmentation conditions are run. | String |
Example
DY.API("event", {
name: "Filter Items",
properties: {
dyType: "filter-items-v1",
filterType: "Color", // Name of filter (Color, Size, Brand, Fit, Author, Keyword, Category...)
filterNumericValue: 4
}
});
Aside from the predefined Event schemas above, visitors can be identified at any other relevant instance during their journey (for example, within the checkout process) by calling the following Identify API.
Note: This event is only required for websites. When using a mobile application, Dynamic Yield handles user identification via the Identify User API function.
Example
Hashed email:
DY.API("identify", {
uid: "c0e93cee791b35af528a825f6476e8108e5f03e481ee39800a31a75559cdba2e", //SHA256 hashed email of the plain text email in lower case
type: "he"
});
External:
DY.API("identify", {
uid: "11251125",
type: "external"
});
- Advanced users only
- Adds an identification method to the current user
- The identification can be later used by advanced users to connect with their own Business Intelligence systems
The user has run a free-style keyword search.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “keyword-search-v1″ | String |
keywords | the search string, as-is | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Keyword Search",
properties: {
dyType: "keyword-search-v1",
keywords: "my search string"
}
});
For the Experience API format, see Keyword Search.The user has logged in. It is recommended that the login event also establish “user identification” (associating a customer ID with a Dynamic Yield user ID). Passing an email as the user ID is usually preferable, as you’ll later be able to use the Dynamic Yield email capabilities for that user. However, any other ID type is supported, including multiple ID types per user.
If users’ email addresses are used as their unique identifier across the site and within the onboarded user data, then the “hashedEmail” field should be filled with SHA256(to_lower_case_(email)) encoded email address. If a custom identifier is used, then it should be passed in the “cuid” and “cuidType” (such as “webId” or “customerId”), instead of the “hashedEmail” field.
When the "cuidType" is external, you must fire the Identify API as well.
You have a few choices of what to include when sending this event:
- Send the event with just a hashed email.
- Send the event with just a non-email CUID (Customer User ID). In this case, you may decide to explicitly specify the type by also setting the “cuidType” property. If cuidType is not set, a default type named “id” is used.
- Send both an email AND a non-email identifier. In this case, both will be linked with each other.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “login-v1″ | String |
hashedEmail | SHA256 encoding of the lowercase email, if the email is known (optional) | String |
cuid | If not identifying by email, pass the customer ID (optional) | String |
cuidType | If not identifying by email, pass the customer ID type (optional) | String |
JavaScript examples (site personalization/script)
DY.API("event", {
name: "Login",
properties: {
dyType: "login-v1",
hashedEmail: DYO.dyhash.sha256("myemail@ gmail.com".toLowerCase()), // SHA256 encoding of the lowercase email, if known (optional)
}
});
DY.API("event", {
name: "Login",
properties: {
dyType: "login-v1",
cuid: "...", // If not identifying by email, pass the customer ID (optional)
cuidType: "..." // If not identifying by email, pass the customer ID type (optional)
}
});
Mark individual user emails to receive or not receive triggered emails. The email recipient list is managed by Dynamic Yield using these events.
Note: Opt-in events are supported only on the client-side.
Message opt-in parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “message-optin-v1” | String |
cuidType | Must be “email” or "external" | String |
plainTextEmail |
A valid plain text email address. If the cuidType is "email", this property is mandatory. Otherwise, use the property externalId. Do not define both properties. Plain text emails are required in this API as we use the email addresses for triggered emails and audience exports. Hashing only works one way, and PII data can not be decrypted. |
String |
externalId |
The external ID to identify the user. Your ESP should recognized this ID and be able to map it to an email address. If the cuidType is "external", this property is mandatory. Otherwise, use the property plainTextEmail. Do not define both properties. Note: External type is supported only by custom ESP and Emarsys integrations (and not by SendGrid or Responsys, for example) |
String |
JavaScript examples (site personalization/script)
DY.API("event", {
name: "message opt in",
properties: {
dyType: "message-optin-v1",
cuidType: "email",
plainTextEmail:"pocih39267@latovic.com"
}
});
DY.API("event", {
name: "message opt in",
properties: {
dyType: "message-optin-v1",
cuidType: "external",
externalId:"852456456"
}
});
Message opt-out parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “message-optout-v1” | String |
cuidType | Must be “he” or "external" | String |
hashedEmail | SHA256 hash of the plain-text email in lower case. If the cuidType is "he", this property is mandatory. Otherwise, use the property externalId. | String |
externalId |
The external ID to identify the user. Your ESP should recognized this ID and be able to map it to an email address. If the cuidType is "external", this property is mandatory. Otherwise, use the property hashedEmail. Note: External type is supported only by custom ESP and Emarsys integrations (and not by SendGrid or Responsys, for example) |
String |
JavaScript examples (site personalization/script)
DY.API("event", {
name: "message opt out",
properties: {
dyType: "message-optout-v1",
cuidType: "email", //can be "external" or "he"
hashedEmail: "REPLACE_WITH_EMAIL_ADDRESS", //mandatory valid hashed email address if cuidType is "he"
}
});
DY.API("event", {
name: "message opt out",
properties: {
dyType: "message-optout-v1",
cuidType: "external", //can be "external" or "he"
externalId: "[REPLACE_WITH_EXTERNAL_ID]", //mandatory if you cuidType is "external"
}
});
The user has subscribed to a newsletter.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “newsletter-subscription-v1” | String |
hashedEmail | “…” // SHA256 encoding of the lowercase email, in textual hexadecimal representation | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Newsletter Subscription",
properties: {
dyType: "newsletter-subscription-v1",
hashedEmail: "DYO.dyhash.sha256("myemail@ gmail.com".toLowerCase())" // SHA256 encoding of the lowercase email,
// in textual hexadecimal representation
}
});
For the Experience API format, see Newsletter Subscription.The user has entered a valid promo code.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “enter-promo-code-v1″ | String |
code | The promo code | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Promo Code Entered",
properties: {
dyType: "enter-promo-code-v1",
code: "..."
}
});
The user has made a purchase.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “purchase-v1” | String |
uniqueTransactionId | Will ensure only one purchase is reported per transaction. Must be a string. Max 64 characters. | String |
value | Total cart value in the actual payment currency | Float (dollars.cents). Number must be positive. Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
currency | currency Optional, but required for multi-currency sites |
The currency that is used for the value List of supported currencies |
cart |
The absolute current cart state. Products should be in order from oldest to newest. Cart Properties: |
|
productId: The SKU exactly as it appears in the product feed |
String |
|
quantity: The total number of items for this SKU | Number | |
itemPrice: The price of the item. Notice that if an item that costs $5 was added twice, it should show $5, and not the total $10. |
Number Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
|
size: Optional The size of the item (for example, L, M, S, or any way you choose to label sizes) |
String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Purchase", // Human-readable name, not used to identify an event type
properties: {
uniqueTransactionId: "123456", // Will remove redundant events. Must be a string. Max 64 characters.
dyType: "purchase-v1", // Identifies this event as a purchase
value: 90.55, // Total cart value in actual payment currency, as float (dollars dot cents)
currency: "any supported currency code", // Optional non-default currency used
cart: [
// itemPrice is per quantity of one, and in the same format as the total "value":
// float of dollars.cents in the payment currency (which is only defined once above)
{
productId: "item-34454", // SKU exactly as in the product feed!
quantity: 1,
itemPrice: 65.87,
size: "XL" // Size is *optional and a customer-specific string*
}, {
productId: "sku-4324-bg",
quantity: 2,
itemPrice: 12.34,
size: "M"
}
]
}
});
For the Experience API format, see Purchase.The user has removed a product from the cart.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “remove-from-cart-v1“ | String |
value | Total value in actual payment currency. | Float (dollars.cents). Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
currency | Optional non-default currency used | String List of supported currencies |
productId | SKU exactly as it appears in the product feed | String |
quantity | Number | |
size | Optional string, customer-specific values | String |
cart Optional, but recommended |
The absolute current cart state. Products should be in order from oldest to newest. Cart Properties: |
|
productId: SKU exactly as it appears in the product feed |
String |
|
quantity | Number | |
itemPrice | Number Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0. |
|
size: Optional | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Remove from Cart",
properties: {
dyType: "remove-from-cart-v1",
value: 34.45,
currency: "any supported currency code",
productId: "gswefd-34-454",
quantity: 1,
size: "XL"
cart: [{
productId: "sku-4324-bg",
quantity: 2,
itemPrice: 12.34,
},
{
productId: "item-34454",
quantity: 1,
itemPrice: 34.45
}
]
}
});
For the Experience API format, see Remove from Cart.Trigger an event when the user has completed the signup process. You have several choices of what to include when sending this event:
- Send the event with just a hashed email.
- Send the event with just a non-email CUID (Customer User ID). In this case, you may decide to specify explicitly the type by also setting the “cuidType” property. If cuidType is not set, a default type named “id” is used.
- Send both an email AND a non-email identifier. In this case, both will be linked with each other.
When the "cuidType" is external, you must fire the Identify API as well.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “signup-v1” | String |
hashedEmail | SHA256 encoding of the lowercase email, if the email is known (optional) | String |
cuid | If not identifying by email, pass the customer ID (optional) | String |
cuidType | If not identifying by email, pass the customer ID type (optional) | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Signup",
properties: {
dyType: "signup-v1",
hashedEmail: "DYO.dyhash.sha256("myemail@ gmail.com".toLowerCase())", // SHA256 encoding of the lowercase email, if the email is known
}
});
For the Experience API format, see Signup.The user has changed the sorting of a product list.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “sort-items-v1” | String |
sortBy | Any of PRICE, AGE, POPULARITY, RATING, OTHER | String |
sortOrder | ASC or DESC | String |
JavaScript Example (Web)
DY.API("event", {
name: "Sort Items",
properties: {
dyType: "sort-items-v1",
sortBy: "PRICE",
sortOrder: "ASC"
}
});
This event updates the current cart state.
It's mandatory for the Exclude items currently in cart filter; for this filter, it must be implemented on every page load.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “sync-cart-v1” | String |
currency | Optional non-default currency used | String List of supported currencies |
cart |
The absolute current cart state (including the last added item). Products should be in order from oldest to newest. Cart Properties: |
|
productId: SKU exactly as it appears in the product feed |
String |
|
quantity | Number | |
itemPrice | Number | |
size: Optional | String |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Sync cart",
properties: {
dyType: "sync-cart-v1",
currency: "any supported currency code", // Optional non-default currency used
cart: [ //Mandatory, the order of products should be from oldest to newest
{
productId: "sku-4324-bg",
quantity: 2,
itemPrice: 12.34,
},
{
productId: "item-34454",
quantity: 1,
itemPrice: 34.45
}
]
}
});
For the Experience API format, see Sync Cart.The user has watched a video (in part or in full). You can distinguish between auto-playing videos and those that were explicitly clicked on by the user.
Parameters
- name: Human-readable name, not used to identify an event type
- properties: A container for the event properties as specified in the table below.
Property | Description | Type |
---|---|---|
dyType | Must be “video-watch-v1″ | String |
itemId | Mandatory string ID – must match an id present in the Content Feed | String |
categories | Optional string | String |
autoplay | true/false. Indicates if video was played automatically or because of a direct user action. False by default. | Boolean |
progress | One of the following values:
|
String |
progressPercent | Only relevant if progress mode is “VIDEO_PROGRESS” | Number |
JavaScript example (site personalization/script)
DY.API("event", {
name: "Video Watch",
properties: {
dyType: "video-watch-v1",
itemId: "...", // Mandatory string ID - must match an id present in the Content Feed
categories: ["Sports", "Baseball"], // Optional, independent of whether an ID was given
autoplay: true,
progress: "VIDEO_PROGRESS",
progressPercent: 65 // Meaning: 65% of video length has passed.
}
});
For the Experience API format, see Video Watch.Custom events
If you want to track an event that is not predefined, you can create a custom event by implementing a snippet using the following structure:
DY.API("event", {
name: "EVENT_NAME",
properties: {
[FIRST PROPERTY NAME]: "[PROPERTY VALUE]", // Optional
[SECOND PROPERTY NAME]: "[PROPERTY VALUE]", // Optional
value: "[MONETARY VALUE]" // Optional
}
})
name: Event name. This name appears in the Dynamic Yield console, when creating an audience, and in the reports.
properties (optional): Any additional information about the event. This enables you to create a more refined audience, not with all users who fired this event, but only users who fired the event with a specific property. For example, if the event is rating a product, you can add the rating score as a property, and create an audience of users who rated a product with a score of 5. There is no limit to the number of properties you can include in an event.
value (optional): Adding a property with the name "value" is different from adding other custom properties. Dynamic Yield uses this property name to describe the monetary value of an event. This enables you to later create a Goal based on the event, set its value to be the same as the event value, and set the primary metric of the experience to be the revenue of this goal.
Note that custom events support only symbols that are encoded with UTF-8 (Basic Multilingual Plane). Some characters with diacritics (additional symbols above or below the letter) are read as the base character. For example, é is processed as e.
Examples:
DY.API("event", {
name: "zoom"
})
DY.API("event", {
name: "Satisfaction Survey",
properties: {
Customer Support: "Satisfied",
Shipping: "Very satisfied"
}
})
DY.API("event", {
name: "Donation",
properties: {
type: "charity",
value: 200.00
}
});
Tip: Usually, firing an event means adding code to your site. However, you can use a template called "Fire Event" in Custom Code campaigns to fire an event without making any code changes. Read more about it in our Community.
Off-site events
You can also fire events from off-site or websites without the Dynamic Yield script (for example, 3rd party websites) using a pixel with the following syntax:
<img height='1' width='1' border='0' src='//px.dynamicyield.com/dpx?sec=[SITE ID]&name=[EVENT NAME]&props={"[FIRST PROPERTY NAME]": "PROPERTY_VALUE", value: "[MONETARY VALUE]"}' />
For example:
<img height='1' width='1' border='0' src='//px.dynamicyield.com/dpx?sec=8765000&name=Product_Return&props={"Number of Products": "2"}'/>
px.dynamicyield.com: If you're using Dynamic Yield with EU data center (that is, if the Dynamic Yield console URL is adm.dynamicyield.eu), change the domain to px-eu.dynamicyield.com.
sec: Site ID. The site ID appears in the URL when you're in the Dynamic Yield console, next to the "SectionId" (It's a 7-digit number that starts with 87 or 98).
name: Event name. This name will appear in the Dynamic Yield console, in the audience condition, and in the reports.
props: The properties and their values you want to send in the event.
Note: If you want to attribute off-site events to your campaigns in experience reports, the attribution window of the campaigns must be set to 1 day or 7 days, but cannot be session-based.
Validating event implementation
A critical part of setting up Dynamic Yield is to validate that your events are firing and do not have any errors. There are 2 ways to validate:
- Implementation Status: A summary of the quality of events fired in the last 12 hours
- Implementation Helper: Immediate debugging tool using your browser
Learn more about validating in the Validating Your Web Implementation article.