.. _html_integration:

################
HTML Integration
################

.. rst-class:: lead
    
    HTML Widgets are the easiest way how to get recommendations into your site.

.. figure:: _static/gui/html_widget.png
  :alt: Recombee HTML Widget
  :scale: 100%
  :align: center

  Setting HTML Widget in the :ref:`Admin UI <admin_ui>`


**************************
Displaying Recommendations
**************************

Follow the :ref:`HTML Widget section in the Getting Started<getting_started_recomms_widget>`.

.. _html_integration_providing_item_id:

*****************
Providing Item Id
*****************

In case of the :ref:`Recommend Items To Item <request-recommend-items-to-item>` :ref:`Scenarios <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.

.. figure:: _static/gui/html_widget_item_id.png
  :alt: Item ID placeholder in the Embed Code
  :scale: 80%
  :align: center

  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 <https://www.shopify.com/>`_ theme, using the `product object <https://shopify.dev/docs/themes/liquid/reference/objects/product>`_:

.. code-block:: html

  <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 :ref:`Recommend Items To Item <request-recommend-items-to-item>` :ref:`Scenarios <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 :ref:`catalog feed<catalog_feeds>` in the `Recombee Admin UI <https://admin.recombee.com>`_ or by :ref:`using an SDK <getting_started_catalog>`.

Sending the interaction can be enabled in the *Embed Code* section. The interaction which is being sent is a :ref:`Detail View<request-add-detail-view>`.


.. figure:: _static/gui/html_widget_send_interaction.png
  :alt: Recombee Admin UI
  :scale: 100%
  :align: center

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

******************************
Optional Embed Code Parameters
******************************

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

filter
======

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

.. code-block:: html

  <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 :ref:`ReQL<reql>` booster. It can be used for example to boost items that are near to the current position of the user:

.. code-block:: html

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


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 <https://tagmanager.google.com/#/home>`_).


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.

.. code-block:: html

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



*******************
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 <https://clearcode.cc/blog/difference-between-first-party-third-party-cookies/>`_.

Cookies set by the Recombee Integration
=======================================

.. list-table::
   :widths: 15 50 25 10
   :header-rows: 1

   * - 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:

.. code-block:: html

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