# Segment Integration

> Source: https://docs.recombee.com/segment

> For the complete documentation index, see [llms.txt](/llms.txt).

**Table of contents**

* [Getting Started](#getting-started)
* [Settings](#settings)
* [Supported Mappings](#supported-mappings)  
   * [Page](#page)  
   * [Track](#track)  
   * [Screen](#screen)  
   * [Alias](#alias)  
   * [Delete User](#delete-user)  
   * [Custom Mappings](#custom-mappings)
* [Reporting Successful Recommendations](#reporting-successful-recommendations)

# Segment Integration

[Segment](https://segment.com) is a Customer Data Platform (CDP).

![](/img/segment/recombee-segment-header.png) 

Segment simplifies collecting and using data from the users of your digital properties (websites, apps, etc). Using it, you can collect, transform, send, and archive your first-party customer data.

The Recombee destination in Segment can send your interaction data (views, purchases, plays, etc.) to Recombee.

Note

This page describes the new version of the Recombee Destination in Segment, called just **Recombee**. For documentation of the old version, called _Recombee AI_, visit the [Segment Documentation](https://segment.com/docs/connections/destinations/catalog/recombee-ai/).

## Getting Started

1. In the Segment web app, navigate to **Connections > Destinations** and click **Add Destination**.
2. Find and select [Recombee](https://app.segment.com/goto-my-workspace/destinations/catalog/actions-recombee) and click **Add Destination**.  
[![The Recombee integration in the Segment Destination Catalog](/img/segment/segment_ui.png)](/img/segment/segment_ui.png)
3. Select a Source to connect to the **Recombee** destination.
4. 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.
5. 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.  
   [![Setting API Identifier and Private Token](/img/segment/segment_settings.png)](/img/segment/segment_settings.png)

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.

## Settings

Database ID

Required: **Yes**

The ID of the Recombee Database into which the interactions will be sent.

---

Private Token

Required: **Yes**

The private token for the Recombee Database used.

---

Database Region

Required: **Yes**

The Recombee cluster where your Database is located. [Learn more](/regions)

---

API URI

Required: **No**

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

---

## Supported Mappings

### Page

If you're new to the Segment Spec, check out the [Page method documentation](https://segment.com/docs/connections/spec/page/) to understand how it works. Here's an example of a Page method call:

JavaScript

```
analytics.page();
```

Segment sends Page calls to Recombee as a [Detail View](/api#request-add-detail-view).

### Track

If you aren't familiar with the Segment Spec, take a look at the [Track method documentation](https://segment.com/docs/connections/spec/track/)to learn about what it does. Here's an example:

JavaScript

```
analytics.track('Video Content Playing', {
  session_id: '12345',
  asset_id: '0129370',
  position: 20,
  total_length: 360,
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',
});
```

The Recombee Destination can process several [Semantic Events](https://segment.com/docs/connections/spec/semantic/).

**Supported [Ecommerce](https://segment.com/docs/connections/spec/ecommerce/v2/) events:**

| Segment Event                                                                                                          | Sent Interaction                                                       |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Product Viewed](https://segment.com/docs/connections/spec/ecommerce/v2/#product-viewed)                               | [Detail View](/api#request-add-detail-view)                            |
| [Product Added](https://segment.com/docs/connections/spec/ecommerce/v2/#product-added)                                 | [Cart Addition](/api#request-add-cart-addition)                        |
| [Product Removed](https://segment.com/docs/connections/spec/ecommerce/v2/#product-removed)                             | [Delete Cart Addition](/api#request-delete-cart-addition)              |
| [Order Completed](https://segment.com/docs/connections/spec/ecommerce/v2/#order-completed)                             | [Purchase](/api#request-add-purchase) for each of the ordered products |
| [Product Added to Wishlist](https://segment.com/docs/connections/spec/ecommerce/v2/#product-added-to-wishlist)         | [Bookmark](/api#request-add-bookmark)                                  |
| [Product Removed from Wishlist](https://segment.com/docs/connections/spec/ecommerce/v2/#product-removed-from-wishlist) | [Delete Bookmark](/api#request-delete-bookmark)                        |
| [Product Shared](https://segment.com/docs/connections/spec/ecommerce/v2/#product-shared)                               | [Bookmark](/api#request-add-bookmark)                                  |

**Supported [Video](https://segment.com/docs/connections/spec/video/) events:**

| Segment Event                                                                                         | Sent Interaction                                                                      |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [Video Playback Started](https://segment.com/docs/connections/spec/video/#video-playback-started)     | [View Portion](/api#request-set-view-portion) with portion = 0                        |
| [Video Content Playing](https://segment.com/docs/connections/spec/video/#video-content-playing)       | [View Portion](/api#request-set-view-portion) with portion = position / total\_length |
| [Video Playback Paused](https://segment.com/docs/connections/spec/video/#video-playback-paused)       | [View Portion](/api#request-set-view-portion) with portion = position / total\_length |
| [Video Playback Completed](https://segment.com/docs/connections/spec/video/#video-playback-completed) | [View Portion](/api#request-set-view-portion) with portion = 1                        |

If you want to send interactions from other types of events, you can create your own custom mappings in the Segment web app. [Learn more below](#custom-mappings)

### Screen

For more details on the Screen method, refer to the [Screen method documentation](https://segment.com/docs/connections/spec/screen/). Here's an example call:

Objective-C

```
[[SEGAnalytics sharedAnalytics] screen:@"Home"];
```

Segment converts Screen calls to [Detail View](/api#request-add-detail-view) interactions.

### Alias

For information about Alias, visit the [Alias method documentation](https://segment.com/docs/connections/spec/alias/). Here's an example of an Alias call:

JavaScript

```
analytics.alias('507f191e81');
```

These Alias calls are mapped to [Merge Users](/api#request-merge-users) calls.

### Delete User

Segment sends a [Delete User](/api#request-delete-user) call to Recombee on deleting a user. All the associated data associated with the user (including interactions) are removed from Recombee.

### Custom Mappings

The new Action Destinations framework in Segment, which this integration uses, allows you to create custom mappings for your events directly in the Segment web app.

To create a custom mapping, open the destination in the Segment web app, navigate to the **Mappings** tab, and click **New Mapping**.

You can add a predefined mapping, but more importantly, right below the predefined mappings, there is a list of all available actions that you can use to create your own custom mappings.

[![Selecting an available action in Segment](/img/segment/segment_mapping_actions.png)](/img/segment/segment_mapping_actions.png)

After selecting an action, you can continue below the list and configure the mapping.

There you can define the event trigger, the fields of the event, and how they correspond to the fields of the interaction.

[![Defining a custom event trigger in Segment](/img/segment/segment_mapping_trigger.png)](/img/segment/segment_mapping_trigger.png)

## Reporting Successful Recommendations

You should 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 [Reported Metrics](/admin_ui#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.