Segment Integration

It simplifies collecting and using data from the users of your digital properties (websites, apps, etc). With Segment, 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.

Tip

Check out the Official Segment Recipe about using Recombee

Getting Started#

1. From the Destinations catalog page in the Segment App, click Add Destination.

2. Search for "Recombee" in the Destinations Catalog, and select the Recombee destination.

   
   Recombee integration in the Segment Destination Catalog#

3. Choose which Source should send data to the "Recombee" destination.

4. Go to the Recombee Admin UI:

   • Choose a Recombee Database into which you want to send the interactions.
   • Pick the Settings section from the menu on the left.
   • In the section find the API Identifier of the Database and the corresponding Private Token

5. In the settings of the Recombee Destination in Segment:

   • set the obtained API Identifier as the Database ID
   • set the obtained Private Token as the API Key
     

6. When you start sending the data from Segment to the Recombee Destination you can:

   • see the numbers of the ingested interactions in the KPI console of the Recombee Admin UI (updated in Real-time)
   • see a particular ingested interaction after clicking on the ID of the item/user in Items/Users catalog sections.

Settings#

Required#

Database ID#

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

API Key#

Corresponding private token.

Optional#

Item ID Property Name#

For each Recombee interaction, a userId and an itemId must be provided.

By setting Item ID Property Name, you can specify the name of the Segment event property from which the itemId will be read.

If you don't provide the Item ID Property Name:

• product_id is used for Ecommerce Events
• content_asset_id / asset_id is used for Video Events
• name property is used if exists

Track Events Mapping#

This Destination can automatically handle various Ecommerce Events and Video Events in the Track call type (see the Track section).

If you are using some custom Events, you can set which Recombee interaction will be sent for each of them.

The value of the mapping is the name of your event, and the key can be one of:

• Bookmark
• Cart Addition
• Detail View
• Purchase
• Rating
  • a property rating must exist and contain a number from interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating.
• View Portion
  • the portion (how much of the content was consumed by the user) is computed from the position and total_length properties (see Content Event Object), or can be given as the portion property (a number between 0 and 1).

API URI#

Specify the URI of the Recombee API that should be used.

Example: rapi.recombee.com (note that protocol is omitted).

This is needed if you are calling the Recombee cluster based in a specific region or you were assigned a custom URI by the Recombee Support team. Otherwise, keep this value unset.

Page#

If you aren't familiar with the Segment Spec, take a look at the Page method documentation to learn about what it does. An example call would look like:

analytics.page();

Segment sends Page calls to Recombee as a Detail View.

Track#

If you aren't familiar with the Segment Spec, take a look at the Track method documentation to learn about what it does. An example call would look like:

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

Recombee Destination can process several Semantic Events:

Ecommerce:

• Product Viewed - sends a Detail View
• Product Added - sends a Cart Addition
• Product Removed - sends a Delete Cart Addition
• Order Completed sends a Purchase for each of the ordered products
  • Product Added to Wishlist - sends a Bookmark
  • Product Shared - sends a Bookmark

Video:

• Following events send a View Portion:
  • Video Playback Started
  • Video Content Playing
  • Video Playback Paused
  • Video Playback Completed

If you want to send interactions from other events, set them to Track Events Mapping in Settings.

Screen#

If you aren't familiar with the Segment Spec, take a look at the Screen method documentation to learn about what it does. An example call would look like:

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

Segment sends Screen calls to Recombee as a Detail View.

Alias#

If you aren't familiar with the Segment Spec, take a look at the Alias method documentation to learn about what it does. An example call would look like:

analytics.alias('507f191e81');

Segment sends Alias calls to Recombee as Merge Users call.

Delete User#

Segment sends a Delete User call to Recombee on deleting a user. All the associated data associated with the user (including interactions) are removed from Recombee.

Reporting of successful recommendations#

You can tell Recombee that particular interaction is based on a successful recommendation (e.g. the recommendations were presented to a user and the user clicked one of the items), by setting the ID of the successful recommendation request (read more details here) to the recomm_id property of a Segment event.

The recomm_id property is recognized in all the events that send interactions.

In case of Order Completed, set the recomm_id to the object of the particular product (products.$.recomm_id) that was ordered thanks to a successful recommendation.

Sending the recomm_id will give you precise numbers about successful recommendations in the KPI section of the Recombee Admin UI. This explicit feedback also helps in optimizing the recommendation models.