---
title: Dynamic Yield Connector Setup Guide
description: This article describes how to set up the Dynamic Yield connector.
url: https://docs.tealium.com/server-side-connectors/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](https://docs.tealium.com/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](https://docs.tealium.com/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](https://docs.tealium.com/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](https://docs.tealium.com/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`. |