Dynamic Yield Connector Setup Guide
This article describes how to set up the Dynamic Yield connector.
Actions
| Action name | AudienceStream | EventStream |
|---|---|---|
| Record pageview | ✗ | ✓ |
| Send event | ✓ | ✓ |
| Send event (batch) | ✓ | ✓ |
| Record engagement | ✗ | ✓ |
| Report engagement (batch) | ✗ | ✓ |
| Upsert or delete a user | ✓ | ✗ |
| Upsert or delete a user (batch) | ✓ | ✗ |
Configuration
Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
After adding the connector, configure the following settings:
- Host
- (Required) Select the host associated with the Dynamic Yield project.
- To point to the EU-based API endpoints, use https://dy-api.eu. To point to the US-based API endpoints, use https://dy-api.com.
- API KEY
- (Required) The Dynamic Yield API key.
Actions
The following section lists the supported parameters for each action.
Record pageview
Parameters
| Parameter | Description |
|---|---|
| User ID | The unique user ID. Valid values are dyid or dyid_server. |
| Session identifier generated by Dynamic Yield | Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. |
| Page Type | (Required) The type of page. Valid fields are: HOMEPAGE, CATEGORY, PRODUCT, CART, and OTHER. |
| Page Location | The type of device or application. Used for targeting experiences and campaigns according to the current location in the app or site. Valid fields are: Page URL (for web), location (for SPAs) or screen name (for mobile apps). |
| Page Referrer | The page referrer domain. Used for targeting experiences according to the previous location in the site or app. |
| Page Locale | Page locale code, such as en_US. |
| Page Data | Additional data related to the page type, such as the product SKU for PRODUCT-type pages. Required only for Category and Product pages. Do not use for Homepage or other types. |
| Device IP | The client IP address for IP filtering. If this value is not passed, the caller IP is used. |
| Channel | The channel you want to monitor. Valid fields are: Web, App, and Kiosk. |
| Active Consent Accepted | User’s consent decision. Valid fields are: true or false. If you do not send this parameter, the API defaults to false. |
Send event
Parameters
| Parameter | Description |
|---|---|
| User ID | The unique user ID. Valid values are dyid or dyid_server. |
| Session identifier generated by Dynamic Yield | Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. |
| Name | (Required) A human-readable name to describe the event. Used to identify standard events and usually corresponds to the schema name. |
| DY Type | Standard event identifier. |
| Value | The total monetary value of the event in the payment currency. For example, the total cart purchased. Valid fields are: add-to-cart-v1, purchase-v1, remove-from-cart-v1, sync-cart-v1. |
| Currency | The payment currency. Valid fields are: add-to-cart-v1, purchase-v1, remove-from-cart-v1, sync-cart-v1. |
| Product ID | The SKU exactly as it appears in the product feed. Valid fields are: add-to-cart-v1, add-to-wishlist-v1, remove-from-cart-v1. |
| Quantity | The total number of items that were added to cart. Valid fields are: add-to-cart-v1, remove-from-cart-v1. |
| Unique Transaction ID | Ensures that only one purchase is recorded for the transaction ID, even if duplicate events are reported. Valid fields are: purchase-v1. |
| CUID | User identifier value. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1. |
| CUID Type | User identifier value type. Use this value to identify users across devices.
|
| Hashed Email | SHA-256 encoding of the lowercase email address. You can use this identifier type instead of cuid and cuidType. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1, message-optout-v1. |
| Phone Number | Use this identifier type to identify users for the SMS channel in Reconnect campaigns. Valid fields are: login-v1. |
| Plain Text Email | A valid plain text email address. Use either plainTextEmail or externalId. Valid fields are: message-optin-v1. |
| External ID | The external ID used to identify the user. Your ESP must be able to recognize this ID and map it to an email address. Use either plainTextEmail OR externalId, not both. Note: The external ID type is supported by custom ESP and Emarsys integrations only. Valid fields are: message-optin-v1, message-optout-v1. |
| Size | Product size. Valid fields are: add-to-wishlist-v1. |
| Filter Type | Filter name. For example, color, size, brand, fit, author, or keyword. Must correspond to a product property in your product feed. Valid fields are: filter-items-v1 |
| Filter Numeric Value | The value that determines how segmentation conditions are fun. Specify a value for this property or for filterStringValue. Valid fields are: filter-items-v1 |
| Filter String Value | The value that determines how segmentation conditions are fun. Specify a value for this property or for filterNumericValue. Valid fields are: filter-items-v1 |
| Attribute Type | The attribute type. For example, color, size, fit, brand, or author. Valid fields are: change-attr-v1. |
| Attribute Value | The new attribute value. For example, the new color is gray. Valid fields are: change-attr-v1. |
| Sort By | Sorting parameter, such as price, age, popularity, rating, or any other you allow. Valid fields are: sort-items-v1. |
| Sort Order | ASC or DESC. Valid fields are: sort-items-v1. |
| Code | The promo code. Valid fields are: enter-promo-code-v1. |
| Keywords | The search string. Valid fields are: keyword-search-v1. |
| Item ID | ID that matches an item ID in the content feed. Valid fields are: video-watch-v1. |
| Categories | Array of video categories. Valid fields are: video-watch-v1. |
| Autoplay | Indicates whether the video played automatically (true) or due to a user action (false). The default is false. Valid fields are: video-watch-v1 |
| Progress | Describes the amount of video played. Possible values:
|
| Progress percent | Indicates how much of a video was watched as a percentage. Valid fields are: video-watch-v1. |
| Product IDs | Array of product identifiers. |
| Quantities | Array of product quantities. |
| Item prices | Array of item prices in Dollars.cents format. |
| Active Consent Accepted | User’s consent decision. Valid fields are: true or false. If you do not send this parameter, the API defaults to false. |
| Store ID | The unique store identifier. For example, for restaurant recommendations. |
| Store Day Part | Use to differentiate campaigns based on the time of day. |
| Device IP | The client IP address for IP filtering. If not passed, the caller IP is used. |
| Device User Agent | For web-based clients, the User-Agent string. If not passed, the API Gateway will check for that header in the HTTPS request. |
| Custom event properties | The custom event properties you want to share. For example, product_category or coupon_code. The event properties value and currency are reserved properties and cannot be mapped here. |
Send event (batch)
Batch limits
This action uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:
- Max number of requests: 10
- Max time since oldest request: 5 minutes
- Max size of requests: 1 MB
Parameters
| Parameter | Description |
|---|---|
| User ID | The unique user ID. Valid values are dyid or dyid_server. |
| Session identifier generated by Dynamic Yield | Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. |
| Name | (Required) A human-readable name to describe the event. Used to identify standard events and usually corresponds to the schema name. |
| DY Type | Standard event identifier. |
| Value | The total monetary value of the event in the payment currency. For example, the total cart purchased. Valid fields are: add-to-cart-v1, purchase-v1, remove-from-cart-v1, sync-cart-v1. |
| Currency | The payment currency. Valid fields are: add-to-cart-v1, purchase-v1, remove-from-cart-v1, sync-cart-v1. |
| Product ID | The SKU exactly as it appears in the product feed. Valid fields are: add-to-cart-v1, add-to-wishlist-v1, remove-from-cart-v1. |
| Quantity | The total number of items that were added to cart. Valid fields are: add-to-cart-v1, remove-from-cart-v1. |
| Unique Transaction ID | Ensures that only one purchase is recorded for the transaction ID, even if duplicate events are reported. Valid fields are: purchase-v1 |
| CUID | User identifier value. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1. |
| CUID Type | User identifier value type. Use this value to identify users across devices.
|
| Hashed Email | SHA-256 encoding of the lowercase email address. You can use this identifier type instead of cuid and cuidType. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1, message-optout-v1. |
| Phone Number | Use this identifier type to identify users for the SMS channel in Reconnect campaigns. Valid fields are: login-v1. |
| Plain Text Email | A valid plain text email address. Use either plainTextEmail or externalId. Valid fields are: message-optin-v1. |
| External ID | The external ID used to identify the user. Your ESP must be able to recognize this ID and map it to an email address. Use either plainTextEmail OR externalId, not both. Note: The external ID type is supported only by custom ESP and Emarsys integrations (and not by SendGrid or Responsys). For example, (message-optin-v1, message-optout-v1). |
| Size | Product size. Valid fields are: add-to-wishlist-v1. |
| Filter Type | Filter name. For example, color, size, brand, fit, author, or keyword. Must correspond to a product property in your product feed. Valid fields are: filter-items-v1 |
| Filter Numeric Value | The value that determines how segmentation conditions are fun. Specify a value for this property or for filterStringValue. Valid fields are: filter-items-v1 |
| Filter String Value | The value that determines how segmentation conditions are fun. Specify a value for this property or for filterNumericValue. Valid fields are: filter-items-v1 |
| Attribute Type | The attribute type. For example, color, size, fit, brand, or author. Valid fields are: change-attr-v1. |
| Attribute Value | The new attribute value. For example, the new color is gray. Valid fields are: change-attr-v1. |
| Sort By | Sorting parameter, such as price, age, popularity, rating, or any other you allow. Valid fields are: sort-items-v1. |
| Sort Order | ASC or DESC. Valid fields are: sort-items-v1. |
| Code | The promo code. Valid fields are: enter-promo-code-v1. |
| Keywords | The search string. Valid fields are: keyword-search-v1. |
| Item ID | ID that matches an item ID in the content feed. Valid fields are: video-watch-v1. |
| Categories | Array of video categories. Valid fields are: video-watch-v1. |
| Autoplay | Indicates whether the video played automatically (true) or due to a user action (false). The default is false. Valid fields are: video-watch-v1. |
| Progress | Describes the amount of video played. Possible values:
|
| Progress percent | Indicates how much of a video was watched as a percentage. Valid fields are: video-watch-v1. |
| Product IDs | Array of product identifiers. |
| Quantities | Array of product quantities. |
| Item prices | Array of item prices in Dollars.cents format. |
| Active Consent Accepted | User’s consent decision. Valid fields are: true or false. If you do not send this parameter, the API defaults to false. |
| Store ID | The unique store identifier. For example, for restaurant recommendations. |
| Store Day Part | Use to differentiate campaigns based on the time of day. |
| Device IP | The client IP address for IP filtering. If not passed, the caller IP is used. |
| Device User Agent | For web-based clients, the User-Agent string. If not passed, the API Gateway will check for that header in the HTTPS request. |
| Custom event properties | The custom event properties you want to share. For example, product_category or coupon_code. The event properties value and currency are reserved properties and cannot be mapped here. |
Record engagement
Parameters
| Parameter | Description |
|---|---|
| User ID | The unique user ID. Valid values are dyid or dyid_server. |
| Session identifier generated by Dynamic Yield | Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. |
| Device IP | The client IP address, for IP filtering. If not passed, the IP of the caller is used. |
| Type | (Required) The engagement type.
|
| Decision ID | The unique decision ID as returned from the chosen endpoint. Required for reporting CLICK or IMP. Decision ID must be an array in base64 format. |
| Variations | The array of multiple variation IDs the user has seen. Required only for reporting explicitly impressions over custom campaigns that return multiple variations on each decision. For example, a slider. |
| Slot ID | The slot ID for the specific clicked product as returned from the chosen endpoint. Not used for custom API campaigns. Required for reporting a click on an API recommendations campaign. |
| Active Consent Accepted | User’s consent decision. Valid fields are: true or false. If you do not send this parameter, the API defaults to false. |
Report engagement (batch)
Batch limits
This action uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:
- Max number of requests: 10
- Max time since oldest request: 1 minutes
- Max size of requests: 1 MB
Parameters
| Parameter | Description |
|---|---|
| User ID | The unique user ID. Valid values are dyid or dyid_server. |
| Session identifier generated by Dynamic Yield | Pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. |
| Device IP | The client IP address, for IP filtering. If not passed, the IP of the caller is used. |
| Type | (Required) The engagement type.
|
| Decision ID | The unique decision ID as returned from the chosen endpoint. Required for reporting CLICK or IMP. Decision ID must be an array in base64 format. |
| Variations | The array of multiple variation IDs the user has seen. Required only for reporting explicitly impressions over custom campaigns that return multiple variations on each decision. For example, a slider. |
| Slot ID | The slot ID for the specific clicked product as returned from the chosen endpoint. Not used for custom API campaigns. Required for reporting a click on an API recommendations campaign. |
| Active Consent Accepted | User’s consent decision. Valid fields are: true or false. If you do not send this parameter, the API defaults to false. |
Upsert or delete a user
Parameters
| Parameter | Description |
|---|---|
| Feed Key | The data feed ID. You can get the ID of an existing data feed by going to Assets › Data Feeds in Experience OS, and looking in the ID column. If you don’t see the ID column, you can add it using the Column dropdown. |
| Action | upsert or delete. The default is delete. |
| CUID | User identifier value. |
| CUID Type | User identifier value type. Use this value to identify users across devices. Use ihe for hashed email addresses or use your custom identifier type. |
| Timestamp | Event timestamp, formatted in milliseconds since Unix epoch that the event occurred. |
| CRM Data | For upsert only. Specify the CRM data that you will be sharing, such as vip_card_member or birthday. |
Upsert or delete a user (batch)
Batch limits
This action uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:
- Max number of requests: 100
- Max time since oldest request: 60 minutes
- Max size of requests: 1 MB
Parameters
| Parameter | Description |
|---|---|
| Feed Key | The data feed ID. You can get the ID of an existing data feed by going to Assets › Data Feeds in Experience OS, and looking in the ID column. If you don’t see the ID column, you can add it using the column dropdown. |
| Action | upsert or delete. The default is delete. |
| CUID | User identifier value. |
| CUID Type | User identifier value type. Use this value to identify users across devices. Use ihe for hashed email addresses or use your custom identifier type. |
| Timestamp | Event timestamp, formatted in milliseconds since Unix epoch that the event occurred. |
| CRM Data | For upsert only. Specify the CRM data that you will be sharing, such as vip_card_member or birthday. |
This page was last updated: March 4, 2024