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

DY.API("event", {
  name: "Add to Cart",
  properties: {
    dyType: "add-to-cart-v1",
    value: 59.13,
    currency: "any supported currency code",
    productId: "item-34454",
    quantity: 1,
    size: "XL",
    cart: [{
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
      },
      {
        productId: "item-34454",
        quantity: 1,
        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 (Web)

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 (web)

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.

Example

Hashed email:

DY.API("identify", {
  uid: "c0e93cee791b35af528a825f6476e8108e5f03e481ee39800a31a75559cdba2e", //SHA256 hashed email of the plain text email in lower case
  type: "he"
});

Email:

DY.API("identify", {
  uid: "sales@dynamicyield.com",
  type: "email"
});

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 (web)

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 (web)

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

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.

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

JavaScript examples (web)

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

JavaScript examples (web)

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 (web)

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 (web)

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 (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
Cart  Recommended. The cart content.
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 (e.g. L, M, S, or any way you choose to label sizes)	String

JavaScript example (web)

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 (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 (web)

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 (web)

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 (web)

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 (web)

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