HTML Integration

Widget Types

HTML Widgets can be configured in the Admin UI. They are deployed into a website or app using an embed code.

We provide widgets both for displaying recommended items (Recommend Items To User, Recommend Items To Item) and for full-text search.

Grid Widget

A box with an adjustable number of items depending on available width (e.g. 5 items horizontally on desktop and 3 items vertically on mobile).

Quick Search Widget

A widget showing full-text search results based on the user’s query. See the Full-text Search Widget section for more details.

Infinite Feed Widget

A feed of items that incrementally loads more content upon reaching the end of the box.

Carousel Widget

A box that loads additional recommendations upon clicking the arrow button.

Displaying Recommendations

For general information about setting up a widget, follow the HTML Widget section in the Getting Started.

Recommending Items to User

In the case of the Recommend Items To User Scenarios, no additional data needs to be provided to the widget - it is sufficient to copy the embed code into your website.

You may want to use some of the embed code's optional parameters (e.g. a dynamic filter), fine-tune the visual appeareance using your own CSS or provide your own user IDs.

Recommending Items to Item

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.

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.

Quick Search Widget

The Quick Search Widget enables you to show items or even Item Segments (categories, genres, artists, etc.) based on the user's full-text search query.

Sections of the Quick Search Widget

Each of the sections is connected to a Scenario.

The number of queried Search requests is equal to the number of used sections.

You can change the order of the displayed sections by moving them (drag and drop) in the Layout menu.

Items

This is the default section which is always present. It shows the list of found items.

In the Content menu, you can specify which item property contains the image URL, title, subtitle, and highlighted information (often used for showing the price).

Hero

An optional section that highlights the top found item.

Segments

An optional section for displaying matching Item Segments (categories, genres, artists, vendors, etc.) by internally using Search Item Segments endpoint.

Segments links

When the user clicks on the displayed Segment, the user shall be redirected to a page corresponding to that Segment (e.g. the category page).

In order to construct this URL, you can provide its prefix and suffix. The resulting URL will be in the form <prefix><sluf of the Segment ID><suffix>.

Example

For prefix https://mypage.com/categories/, suffix .html and Segment ID Office Electronics the resulting URL will be https://mypage.com/categories/office-electronics.html.

Deploying the Quick Search Widget

Copy the embed code into the place where the search input shall be rendered.

Search settings

On navigating to Input and choosing the Settings section, you can specify e.g. how often the search requests will be fired (minimal number of characters, debounce) and the behavior of the submit button.

Submitting the search

You may want to redirect the user to a dedicated search page upon submitting the search (by clicking the Search button or by pressing the Enter key).

You can specify the path of the search page and the name of the query parameter that shall contain the user's search query.

If you don't have such a page, you can disable the Search button here and use only the Quick Search Widget.

Fine-tuning the visual appearance

Recommendation Widgets

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 (Cascading Style Sheets) 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

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:

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

Quick Search Widget

Search widget DOM elements have static class names in the form of recombee-quick-search-widget-*, which do not change. You can use these classes to provide custom CSS. Please do not use class names in the form of rcmbws-*, as these are generated and can change in future releases.

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>

Hiding an empty widget

In some cases, such as your database being empty or the widget scenario produces no results due to e.g. applied filters, the widget may fetch zero items. You may want to hide the widget itself and/or some other elements in your page such as a heading preceding the widget content.

• hideOnEmptyRecommendations: The widget is hidden when no items are available.
• hideOnEmptyRecommendationsElementsSelectors: Selected elements in page are hidden when no items are available.

<script>
	recombeeIntegration({
		type: 'InitializeRecommendationWidget',
		rootElementId: 'widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb',
		widgetId: '1043d1a3-d5ec-4528-b10b-7e2678f941cb',
		hideOnEmptyRecommendations: true,
		hideOnEmptyRecommendationsElementsSelectors: ['.widget-title'],
	});
</script>

Using widget data programmatically

You can supply a callback function that receives valuable data about each recommendation request made by the widget:

<script>
	recombeeIntegration({
		type: 'InitializeRecommendationWidget',
		rootElementId: 'widget-root-1043d1a3-d5ec-4528-b10b-7e2678f941cb',
		widgetId: '1043d1a3-d5ec-4528-b10b-7e2678f941cb',
		onRecommResponse: function(recombeeRequest, recombeeResponse, url, request, response) {
			console.log(recombeeRequest, recombeeResponse, url, request, response);
		},
	});
</script>

• Callback parameters:
  • recombeeRequest: Recombee API client request, either single request or a Batch.
  • recombeeResponse: Resulting recommendations data, either single response or Batch response.
  • url: Recombee API URL to which the request was sent.
  • request: Standard fetch RequestInit object.
  • response: Standard fetch Response object.

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 Widget Integration

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>