Dynamic Yield Connector Setup Guide

Actions

<<<<<<< Updated upstream ======= >>>>>>> Stashed changes

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. For example, customer_id, account_id, or email. Note: Do not include any personal identifying information in this value. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1, message-optin-v1, message-optout-v1.
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: VIDEO_STARTED: The video started playing. Does not indicate if the video was played until the end or any specific time marker. PREROLL_FINISHED: The pre-roll finished playing. VIDEO_FINISHED: The video finished playing whether or not pre-roll was included. VIDEO_PROGRESS: If the client can periodically report fine-grained progress in percentages within the video, use this value together with the progressPercent property. The default is VIDEO_STARTED. Valid fields are: video-watch-v1.
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. For example, customer_id, account_id, or email. Note: Do not include any personal identifying information in this value. Valid fields are: identify-v1, login-v1, signup-v1, newsletter-subscription-v1, message-optin-v1, message-optout-v1.
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: VIDEO_STARTED: The video started playing. Does not indicate if the video was played until the end or any specific time marker. PREROLL_FINISHED: The pre-roll finished playing. VIDEO_FINISHED: The video finished playing whether or not pre-roll was included. VIDEO_PROGRESS: If the client can periodically report fine-grained progress in percentages within the video, use this value together with the progressPercent property. The default is VIDEO_STARTED. Valid fields are: video-watch-v1.
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. Use CLICK or IMP (impressions) for API custom code campaigns. Use SLOT_CLICK for API recommendation campaigns. SLOT_IMP for QSR recommendation campaigns.
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. Use CLICK or IMP (impressions) for API custom code campaigns. Use SLOT_CLICK for API recommendation campaigns. SLOT_IMP for QSR recommendation campaigns.
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.