HTML Integration

HTML Widgets are the easiest way how to get recommendations into your site.

Recombee HTML Widget

Setting HTML Widget in the Admin UI

Displaying Recommendations

Follow the HTML Widget section in the Getting Started.

Providing Item Id

In case of the Recommend Items To Item Scenarios (e.g. at product detail, read next, watch next, etc.), ID of the currently displayed item needs to be provided to the HTML Integration.

Item ID placeholder in the Embed Code

Item ID placeholder in the Embed Code

Different systems have different ways to acquire the item ID. Here is an example of setting the item ID in a Shopify theme, using the product object:

<script>
  recombeeIntegration({
    "type": "SetDefaults",
    "itemId": "{{product.id}}",
    "publicToken": "e2RcU3jPQy1sr6CSIewjbh6IsKmMsaGT4KL4uV8kqWlBkx5hgHg7VYRWf70UFZ9D",
    "databaseId": "my-recombee-database",
    "rapiHostname": "client-rapi.recombee.com:443"
  });
</script>

Sending Interactions

In case of the Recommend Items To Item Scenarios the HTML Integration can (besides showing recommendations to the users in the Widget) also automatically send information about viewing the item (product, article, etc.) by the particular user to Recombee.

This simplifies the basic integration of Recombee into your website, as the only step left which is not covered by the HTML Integration is providing the catalog of your Items. This can be done by setting a catalog feed in the Recombee Admin UI or by using an SDK.

Sending the interaction can be enabled in the Embed Code section. The interaction which is being sent is a Detail View.

Setting HTML Widget in the Recombee Admin UI

To send the interaction, enable the Also send Detail View interaction option

Fine-tuning the visual appearance

You can fine-tune the visual appearance of an element in the widget to exactly match the style of your website by providing a custom class name for the element and using your own CSS to change the element’s appearance.

You can add your custom class names at four places in the Widget Editor using the {} icon:

  • The Grid Box around the whole widget

  • The Item Box around a single recommended item

  • Image of a recommended item

    • Here you can apply the class names either to the wrapper around the image, or the img tag itself

  • Individual Properties of a recommended item

Setting Class Names to the HTML Widget Element

Setting the price-row class name to the row with the price

Class Name Templates

In the case of applying the class names to elements that belong to a particular recommended item (Image and Properties sections), you can use the property values of the particular item to construct the class names using the ${context.entity.propertyName} syntax.

Assume the following item:

Item ID

isOnSale (bool)

reviewRating (int)

item-42

true

5

Then setting:

  • on-sale-${context.entity.isOnSale} generates on-sale-true class name attributes

  • rating rating-${context.entity.reviewRating} generates rating rating-5 class name attributes

Optional Embed Code Parameters

You can set the following optional parameters to the InitializeRecommendationWidget call:

filter

An ad-hoc ReQL filter. It can be used for example to show items only from a particular category:

<script>
  recombeeIntegration({
    "type": "InitializeRecommendationWidget",
    "rootElementId": "widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "widgetId": "1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "filter": `'category' == "sofas"`
  });
</script>

booster

An ad-hoc ReQL booster. It can be used for example to boost items that are near to the current position of the user:

<script>
  recombeeIntegration({
    "type": "InitializeRecommendationWidget",
    "rootElementId": "widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "widgetId": "1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "booster": "if earth_distance(50.075538, 14.437800, 'latitude', 'longitude') < 10000 then 2 else 1"
  });
</script>

logic

The Logic can be set to e.g. send dynamic parameters:

<script>
  recombeeIntegration({
    "type": "InitializeRecommendationWidget",
    "rootElementId": "widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "widgetId": "1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "logic": {
      "name": "recombee:popular",
      "settings": {
        "userSegmentFilter": `'country' == "US"`
      }
    }
  });
</script>

Positioning of the widget

By default, the position of the widget on your page is determined by the position of the div element generated for you in the embed code snippet.

However, in some cases, you may want to set the position of the widget programmatically. This can be for example in the case that you are deploying the widget using some tag manager (such as Google Tag Manager).

You can specify where the widget will be rendered by giving its relative position to another element.

Use one of these optional parameters to specify this element:

  • insertBeforeElementSelector: The widget will be inserted before the first element matching this selector (id, class, etc.).

  • insertAfterElementSelector: The widget will be inserted after the first element matching this selector.

  • prependToElementSelector: The widget will be inserted as the first child of the first element matching this selector.

  • appendToElementSelector: The widget will be inserted as the last child of the first element matching this selector.

<script>
  recombeeIntegration({
    "type": "InitializeRecommendationWidget",
    "rootElementId": "widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "widgetId": "1043d1a3-d5ec-4528-b10b-7e2678f941cb",
    "appendToElementSelector": ".content"
  });
</script>

Usage with Google Tag Manager

To deploy a widget using GTM, create a Custom HTML Tag and copy-paste the widget embed code to the Tag HTML content.

Set a Page View trigger for pages where the widget should be deployed and use positioning parameters to insert the widget to a specific place on your page.

Cookies Information

To provide the most relevant recommendations, Recombee by default identifies the user using first-party cookies on the user’s browser.

The cookie is set by Recombee Integration script, which is used to track interactions or render recommended items in Recommendation Widget. The cookie doesn’t identify your users personally.

Important

You may need to notify your users about the use of tracking cookies depending on your user’s country privacy laws. This is usually done by using a cookie manager deployed to your website. Please consult your legal team to determine whether this step is necessary.

As we use first-party cookies, Recombee tracks your users only at your website - Recombee does no cross-site tracking. Read more about the difference between first-party and third-party cookies here.

Cookies set by the Recombee Integration

Name

Description

Duration

Data Type

_rcmbid

_rcmbid is set each time a user lands on a page with the Recombee Integration script. The cookie is used to preserve the unique Recombee User ID. This ensures that all interactions performed by the unique visitor are attributed to a common anonymous ID.

365 days, refreshed on each visit

String

Users with Disabled Cookies

Recombee doesn’t track or record users who have cookies disabled.

Using your own tracking of users

If you already track the users at your site, you can provide the ID of the user to the Recombee Integration script. You can select this option in the Embed Code section when creating the Widget.

In this case, no cookie is set by the Recombee HTML Integration.

Example

Here is an example of using the Recombee with Google Analytics user IDs:

<script>window.recombeeIntegration=window.recombeeIntegration||function(){(recombeeIntegration.q=recombeeIntegration.q||[]).push(arguments)};recombeeIntegration.l=+new Date;</script>
<script>
  ga(function(tracker) {
    var userId = tracker.get('clientId');
    recombeeIntegration({
      "type": "SetDefaults",
      "userId": userId,
      "publicToken": "e2RcU3jPQy1sr6CSIewjbh6IsKmMsaGT4KL4uV8kqWlBkx5hgHg7VYRWf70UFZ9D",
      "databaseId": "my-recombee-database",
      "rapiHostname": "client-rapi.recombee.com:443"
    });
    recombeeIntegration({
      "type": "InitializeRecommendationWidget",
      "rootElementId": "widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb",
      "widgetId": "1043d1a3-d5ec-4528-b10b-7e2678f941cb"
    });
  });
</script>
<script defer src="https://web-integration.recombee.com/v1/recombee.js"></script>
<div id="widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb"></div>