# Recombee Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Recombee** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) * This integration is **partner owned.** Please reach out to the partner's support for any issues. > \[!NOTE] > > This page is about the Recombee Destination. See below for information about other versions of the Recombee destination: > > * [Recombee AI](/docs/segment/connections/destinations/catalog/recombee-ai) [Recombee](https://recombee.com/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners) is a Recommender as a Service, offering precise content or product recommendations and personalized search based on user behavior. Use this Segment destination to send your interaction data (for example, views, purchases, or plays) to Recombee. This destination is maintained by Recombee. For any issues with the destination, [contact the Recombee Support team](mailto:support@recombee.com). ## Benefits of Recombee (Actions) vs Recombee AI Classic The new Recombee destination built on the Segment Actions framework provides the following benefits over the classic Recombee AI destination: * **Streamlined Configuration**: You can now create mappings in a dedicated tab in the Segment web app, as opposed to needing to edit this in the destination's settings. This allows you to configure the mappings on a per-event basis and makes it easier to verify that your mappings work as intended. * **Removable Bookmarks**: You can now use the [Delete Bookmark Action](#delete-bookmark) to remove the bookmark interaction from the Recombee database. ## Migration from the classic Recombee AI destination Recombee recommends ensuring that a Recombee (Actions) destination and a classic Recombee AI destination connected to the same source are not enabled at the same time in order to prevent errors. ### Configuration changes Recombee made the following configuration changes when setting up the new destination: * Renamed the API Key setting to Private Token: This better reflects the type of token required. * **Removed the Track Events Mapping setting**: If you want to map custom events to Recombee interactions, create your own mappings on the Mappings tab in the Segment app. * **Removed the Item ID Property Name setting**: This functionality is now available in Segment's native Mappings tab. Ensure that your mappings use the desired property for the **Item ID** action field. * **In presets, the **Item ID** property is determined differently**: In the default settings, the `asset_id` property (or `sku` for Ecommerce events) is now the fallback property, instead of `name`. The `name` property is never used by default, as it may not conform to the required **Item ID** format. The property `content_asset_id` (or the first ID in `content_asset_ids`,) is now the default **Item ID** only in Video events, where they are always present. ## Getting started 1. If you don't already have one, set up a [Recombee account](https://recombee.com/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners). 2. From the Segment web app, navigate to **Connections > Destinations** and click **Add Destination**. 3. Select **Recombee** and click **Add Destination**. 4. Select an existing Source to connect to Recombee. 5. Navigate to the [Recombee Admin UI](https://admin.recombee.com) and complete the following actions: * Choose the Recombee Database where you want to send the interactions. * Click **Settings** in the menu on the left. * In the **API ID & Tokens** settings section, find the **Database ID** and the **Private Token** of the Database. 6. Back in the Segment app, navigate to the settings page of the Recombee destination you created. * Copy the **Database ID** from the Recombee Admin UI and paste it into the **Database ID** field in the destination settings. * Copy the **Private Token** from the Recombee Admin UI and paste it into the **Private Token** field in the destination settings. Once you send the data from Segment to the Recombee destination, you can: * Open the KPI console of the [Recombee Admin UI](https://admin.recombee.com) to see the numbers of the ingested interactions (updated in realtime). * Select the ID of an Item (or User) in the Items (or Users) catalog section in the Admin UI to view a specific ingested interaction. ## Destination Settings | Field | Description | Required | Type | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | API URI | URI of the Recombee API that should be used. \*Keep this field empty unless you are calling the Recombee cluster based in a specific region or you were assigned a custom URI by the Recombee Support team.\* | No | string | | Database ID | The ID of the Recombee Database into which the interactions will be sent. | Yes | string | | Database Region | The Recombee cluster where your Database is located. \[Learn more]\(https://docs.recombee.com/regions) | Yes | select | | Private Token | The private token for the Recombee Database used. | Yes | password | ## Available Presets Recombee has the following presets | Preset Name | Trigger | Default Action | | ----------------------------------------- | ---------------------------------------------------------------- | -------------------------------- | | Ecommerce - Order Completed | Event type = "track" and event = "Order Completed" | Add Purchase | | Video - Playback Completed | Event type = "track" and event = "Video Playback Completed" | Set View Portion | | Ecommerce - Product Removed | Event type = "track" and event = "Product Removed" | Delete Cart Addition | | Video - Playback Started | Event type = "track" and event = "Video Playback Started" | Set View Portion | | Screen - Viewed | Event type = "screen" | Add Detail View | | Video - Content Playing | Event type = "track" and event = "Video Content Playing" | Set View Portion from Watch Time | | Page - Viewed | Event type = "page" | Add Detail View | | Ecommerce - Product Removed from Wishlist | Event type = "track" and event = "Product Removed from Wishlist" | Delete Bookmark | | Ecommerce - Product Added to Wishlist | Event type = "track" and event = "Product Added to Wishlist" | Add Bookmark | | Ecommerce - Product Viewed | Event type = "track" and event = "Product Viewed" | Add Detail View | | Alias | Event type = "alias" | Merge Users | | Ecommerce - Product Added | Event type = "track" and event = "Product Added" | Add Cart Addition | | Ecommerce - Product Shared | Event type = "track" and event = "Product Shared" | Add Bookmark | | Video - Playback Paused | Event type = "track" and event = "Video Playback Paused" | Set View Portion from Watch Time | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Recombee-supported actions: > \[!NOTE] > > Individual destination instances have support a maximum of 50 mappings. * [Add Cart Addition](#add-cart-addition) * [Set View Portion from Watch Time](#set-view-portion-from-watch-time) * [Delete Bookmark](#delete-bookmark) * [Add Detail View](#add-detail-view) * [Add Rating](#add-rating) * [Merge Users](#merge-users) * [Add Bookmark](#add-bookmark) * [Delete Cart Addition](#delete-cart-addition) * [Add Purchase](#add-purchase) * [Set View Portion](#set-view-portion) ### Add Cart Addition Adds a cart addition of the given item made by the given user. Add Cart Addition is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Added"` | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | | User ID | The ID of the user who added the item to the cart. | Yes | STRING | | Item | The item that was added to the cart. | Yes | OBJECT | | Timestamp | The UTC timestamp of when the cart addition occurred. | No | STRING | | Recommendation ID | The ID of the clicked recommendation (if the cart addition is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the cart addition. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Set View Portion from Watch Time Sets the viewed portion of a given item (e.g. a video or article) by the given user. **Use this action when you have the watch time of the item (e.g. in seconds) instead of the portion watched.** Set View Portion from Watch Time is a **Cloud** action. | Field | Description | Required | Type | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who viewed a portion of the item. | Yes | STRING | | Item ID | The viewed item. | Yes | STRING | | Timestamp | The UTC timestamp of when the view portion occurred. | No | STRING | | Portion | The portion of the item that the user viewed. | Yes | OBJECT | | Session ID | The ID of the session in which the user viewed the item. | No | STRING | | Recommendation ID | The ID of the clicked recommendation (if the view portion is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the view portion. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Delete Bookmark Deletes a bookmark of the given item made by the given user. Delete Bookmark is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Removed from Wishlist"` | Field | Description | Required | Type | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who bookmarked the item. | Yes | STRING | | Item ID | The item that was bookmarked. | Yes | STRING | | Timestamp | The UTC timestamp of when the bookmark occurred. If the timestamp is omitted, then all the bookmarks with the given \`userId\` and \`itemId\` are deleted. | No | STRING | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Add Detail View Adds a detail view of the given item made by the given user. Add Detail View is a **Cloud** action. | Field | Description | Required | Type | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who viewed the item. | Yes | STRING | | Item ID | The viewed item. | Yes | STRING | | Timestamp | The UTC timestamp of when the view occurred. | No | STRING | | Duration | The duration of the view in seconds. | No | INTEGER | | Recommendation ID | The ID of the clicked recommendation (if the view is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the view. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Add Rating Adds a rating of the given item made by the given user. Add Rating is a **Cloud** action. | Field | Description | Required | Type | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who submitted the rating. | Yes | STRING | | Item ID | The rated item. | Yes | STRING | | Timestamp | The UTC timestamp of when the rating occurred. | No | STRING | | Rating | The rating of the item rescaled to interval \[-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion. | Yes | NUMBER | | Recommendation ID | The ID of the clicked recommendation (if the rating is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the rating. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Merge Users Merges interactions (purchases, ratings, bookmarks, detail views, ...) of two different users under a single user ID. Merge Users is a **Cloud** action. The default Trigger is `type = "alias"` | Field | Description | Required | Type | | ---------------- | ----------------------------------------------------------------------- | -------- | ------- | | Target User ID | The ID of the target user that will be \*\*kept\*\* after the merge. | Yes | STRING | | Source User ID | The ID of the source user that will be \*\*deleted\*\* after the merge. | Yes | STRING | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Add Bookmark Adds a bookmark of the given item made by the given user. Add Bookmark is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Added to Wishlist"` | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who bookmarked the item. | Yes | STRING | | Item ID | The bookmarked item. | Yes | STRING | | Timestamp | The UTC timestamp of when the bookmark event occurred. | No | STRING | | Recommendation ID | The ID of the clicked recommendation (if the bookmark is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the bookmark. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Delete Cart Addition Deletes a cart addition of the given item made by the given user. Delete Cart Addition is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Removed"` | Field | Description | Required | Type | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who added the item to the cart. | Yes | STRING | | Item ID | The item that was added to the cart. | Yes | STRING | | Timestamp | The UTC timestamp of when the cart addition occurred. If the timestamp is omitted, then all the cart additions with the given \`userId\` and \`itemId\` are deleted. | No | STRING | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Add Purchase Adds a purchase of the given item(s) made by the given user. Add Purchase is a **Cloud** action. | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The ID of the user who purchased the item(s). | Yes | STRING | | Items | The items that were purchased. | Yes | OBJECT | | Timestamp | The UTC timestamp of when the purchase occurred. | No | STRING | | Recommendation ID | The ID of the clicked recommendation (if the purchase is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the purchase. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ### Set View Portion Sets the viewed portion of a given item (e.g. a video or article) by the given user. **Use this action when you have the viewed portion as a number between 0 and 1.** Set View Portion is a **Cloud** action. | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | | User ID | The ID of the user who viewed a portion of the item. | Yes | STRING | | Item ID | The viewed item. | Yes | STRING | | Timestamp | The UTC timestamp of when the view portion occurred. | No | STRING | | Portion | The viewed portion of the item as a number in the interval \[0.0,1.0], where 0.0 means the user viewed nothing and 1.0 means the full item was viewed. It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the \`portion\` should still be \`0.1\`. | Yes | NUMBER | | Session ID | The ID of the session in which the user viewed the item. | No | STRING | | Recommendation ID | The ID of the clicked recommendation (if the view portion is based on a recommendation request). | No | STRING | | Additional Data | Additional data to be stored with the view portion. \*Keep this field empty unless instructed by the Recombee Support team.\* | No | OBJECT | | Enable Batching? | When enabled, Segment will send events in batches. | No | BOOLEAN | ## Reporting successful recommendations You can inform Recombee that a specific interaction resulted from a successful recommendation (meaning the recommendations were presented to a user and the user clicked on one of the items) by setting the ID of the successful recommendation request in the `Recommendation ID` field of the action (this is the `recomm_id` property by default). You can read more about this setting in Recombee's [Reported Metrics documentation](https://docs.recombee.com/admin_ui.html#reported-metrics) Sending the `Recommendation ID` gives you precise numbers about successful recommendations in the KPI section of the [Recombee Admin UI](https://admin.recombee.com). This explicit feedback also helps improve the output of the recommendation models. ## Engage You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo). For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`. When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync. > \[!NOTE] > > Real-time audience syncs to Recombee may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected. ## Settings Segment lets you change these destination settings from the Segment app without having to touch any code. | Field | Description | Required | Type | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | API URI | URI of the Recombee API that should be used. \*Keep this field empty unless you are calling the Recombee cluster based in a specific region or you were assigned a custom URI by the Recombee Support team.\* | No | string | | Database ID | The ID of the Recombee Database into which the interactions will be sent. | Yes | string | | Database Region | The Recombee cluster where your Database is located. \[Learn more]\(https://docs.recombee.com/regions) | Yes | select | | Private Token | The private token for the Recombee Database used. | Yes | password |