Events for Web

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 (item or items added that triggered the event only). Note that this is not all the items in the cart. See the code example that follows after this table (productId "item-34454", quantity 2, itemPrice 59.13: Value is 118.26. The other item in the cart is not included.)	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. 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: "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 started the application process for a product. This is a required event for Financial Institution sites.

Parameters

• name: Human-readable name, not used to identify an event type.
• properties: A container for the event properties as specified in the following table.

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. 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: "Application",
  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 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, website visitors can be identified at any other relevant instance during their journey (for example, within the checkout process) by calling the following Identify API.

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

Use to identify visitors at any point during their journey on your website, such as during the checkout process. 

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 “identify-v1”	String
cuid	User identifier value	String
cuidType	The identifier type should be your way of identifying the user across devices (for example, customer_id or account_id). Note: Do not include any personal information in this ID.	String
hashedEmail Optional	If you use hashed email to identify your users, you can use this param instead of cuid and cuidType. The value should be SHA256 encoding of the lowercase email address.	String
phoneNumber Optional	You can add the user’s phone number as another identification property. Can be used for triggering SMS campaigns.	A phone number (national and local numbers) in E.164 format.

Examples

Email identifier

DY.API("event", {
  name: "Identify",
  properties: {
    dyType: "identify-v1",
    hashedEmail: DYO.dyhash.sha256("myemail@gmail.com".toLowerCase()), // SHA256 encoding of the lowercase email.
    phoneNumber:"+972503803434"
  }
  }
});

Non-email identifier

DY.API("event", {
  name: "Identify",
  properties: {
    dyType: "identify-v1",
    cuid: "95764245",
    cuidType: "EcommerceID",
    phoneNumber:"+972503803434"
  }
  }
});

For the Experience API format, see Identify User.

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.

Indicates that a user has logged in. 

Use this event whenever users log in to your site or app. You can use this event for segmenting your traffic (for example, users who logged in in the past 30 days). This event also matches a user identity to the device that is being used, similar to how the Signup, Newsletter Subscription, and the generic Identify User events match the user's identity. 

If you're using users' email addresses as their unique identifier across the site and within the onboarded user data, then the hashedEmail field should be filled with a SHA256(to_lower_case_(email)) encoded email address. If a custom identifier is used, it should be passed in the cuid and cuidType parameters (such as “webId” or “customerId”), rather than the hashedEmail field.

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
cuid	User identifier value	String
cuidType	The identifier type should be your way of identifying the user across devices (for example, customer_id or account_id). Note: Do not include any personal information in this ID.	String
hashedEmail Optional	If you use hashed email to identify your users, you can use this param instead of cuid and cuidType. The value should be SHA256 encoding of the lowercase email address.	String
phoneNumber Optional	You can add the user’s phone number as another identification property. Can be used for triggering SMS campaigns.	A phone number (national and local numbers) in E.164 format.

Examples

DY.API("event", {
  name: "Login",
  properties: {
    dyType: "login-v1",
    hashedEmail: DYO.dyhash.sha256("myemail@gmail.com".toLowerCase()), // SHA256 encoding of the lowercase email.
    phoneNumber:"+972503803434"
  }
});


DY.API("event", {
  name: "Login",
  properties: {
    dyType: "login-v1",
    cuid: "156498191"
    cuidType: "EcommerceID"
    phoneNumber:"+972503803434"
  }
});

For the Experience API format, see Login.

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
cuid	User identifier value	String
cuidType	The identifier type should be your way of identifying the user across devices (for example, customer_id or account_id). Note: Do not include any personal information in this ID.	String
hashedEmail Optional	If you use hashed email to identify your users, you can use this param instead of cuid and cuidType. The value should be SHA256 encoding of the lowercase email address.	String
phoneNumber Optional	You can add the user’s phone number as another identification property. Can be used for triggering SMS campaigns.	A phone number (national and local numbers) in E.164 format.

Example 

DY.API("event", {
  name: "Newletter Subscription",
  properties: {
    dyType: "newsletter-subscription-v1",
    hashedEmail: DYO.dyhash.sha256("myemail@gmail.com".toLowerCase()), // SHA256 encoding of the lowercase email.
    phoneNumber:"+972503803434"
  }
});


DY.API("event", {
  name: "Newletter Subscription",
  properties: {
    dyType: "newsletter-subscription-v1",
    cuid: "156498191"
    cuidType: "EcommerceID"
    phoneNumber:"+972503803434"
  }
});

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 Optional, but required for multi-currency sites	currency	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. Note that if an item that costs $5 was added twice, it shows $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 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 Optional, but required for multi-currency sites	currency	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. Note that if an item that costs $5 was added twice, it shows $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: "Submission", // 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 address.
• Send the event with just a non-email CUID (Customer User ID). In this case, you might decide to 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 “signup-v1”	String
cuid	If not identifying by email, pass the customer ID (optional)	String
cuidType	The identifier type should be your way of identifying the user across devices (for example, customer_id or account_id). Note: Do not include any personal information in this ID.	String
hashedEmail Optional	If you use hashed email to identify your users, you can use this param instead of cuid and cuidType. The value should be SHA256 encoding of the lowercase email address.	String
phoneNumber Optional	You can add the user’s phone number as another identification property. Can be used for triggering SMS campaigns.	A phone number (national and local numbers) in E.164 format.

 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.
    phoneNumber:"+972503803434"
  }
});


DY.API("event", {
  name: "Signup",
  properties: {
    dyType: "signup-v1",
    cuid: "156498191"
    cuidType: "EcommerceID"
    phoneNumber:"+972503803434"
  }
});

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 (site personalization/script)

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: VIDEO_STARTED (default): means that the video has started playing. Does not indicate whether it was then watched till the end or up to any specific marker. PREROLL_FINISHED: means that the pre-roll was watched in full. VIDEO_FINISHED: means that the content was watched in full (whether or not a pre-roll was included) VIDEO_PROGRESS: if the client-side is able to periodically report fine-grained progress in percentage within the video, use with value in conjunction with the “progressPercent” property.	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.

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 
   } 
});