Integrate API-Based Smart Recommender

API-Based Smart Recommender is one of the visualization options that allows you to design your own Smart Recommender widgets on your end with Insider's recommendation abilities and integrate them into Insider's Smart Recommender API. 

You create and edit all campaign configurations like segmentation, and A/B test, and track recommendation analytics from InOne panel while you design Smart Recommender widgets on your end and integrate them into Smart Recommender API. You can integrate API-based Smart Recommender in two steps:

1. Implement event integration
2. Build an HTML design

1. Implement event integration

To deliver the recommended items in your visual design, first, you need to integrate your design into Insider's Smart Recommender API.

After you create the recommendation campaign and launch it, you can check if all works properly from your website:

1. Go to your website, open the console, and paste the code below into the live expression shown below;

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) { 
    console.log(data);
});

2. You need to refresh the page to trigger the event after you paste the code. You should get an object as below:

This object contains the variationId, campaignId, and recommended products which are created and filtered with the recommendation strategy you have configured while you create the Smart Recommender campaign on Insider's InOne panel.

• campaignId: All Smart Recommender campaigns are created with a unique campaignId and this value identifies the campaign on all integrations.
• variationId: Inside the campaigns, you can create multiple variations to show different personalizations. Each variation has its unique variationId.

3. To get the campaignId, navigate to the Web Smart Recommender listing page. Click Details against the campaign of which you want to get the ID.

4. Copy this ID and go to your website again.

5. Open the console and add your if condition to specify the campaign data you want to put on the design:

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) { 
    if (data.campaignId === 237669) {
        console.log(data);
    }
});

6. Refresh the page, then you can get your desired campaign data.

After you check if everything works properly, copy the JavaScript snippet below to the respective pages on your website to get the data object.

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) { 
    if (data.campaignId === 123456) {
        console.log(data);
    }
});

2. Build and HTML design

With the API-based campaign type, you can create your own HTML design for the recommended products with one of the following approaches:

• If you prefer to keep track of the campaign analytics on an analytics tool other than InOne, you can create your design with any type of HTML/CSS structure.
• If you want to monitor the campaign analytics, such as viewable impressions, clicks, add-to-carts, and purchases, for the recommended products in InOne, it's best to design your layout within Insider's predefined HTML structure.

A widget should consist of four main elements that require different HTML structures:

• Main Container
• Products Container
• Product Box
• Optional CTA Button Container

Desktop Web Template

Each element of Visual Smart Recommender requires a different HTML structure.

In the below template, classes and attributes are the unique identifiers. Regardless of the positioning of the classes, you need to inject each container in the same order. 

<div class="ins-preview-wrapper-{variationId}">
    <div class="ins-web-smart-recommender-body" data-recommended-items="["{productId1}",' +' "{productId2}", "{productId3}", ...>">
        <div class="ins-web-smart-recommender-box-item">
            <div class="ins-product-box ins-element-link ins-add-to-cart-wrapper ins-sr-api" ins-product-id="{product's id}" event-collection="true"></div>

        </div>
    </div>
</div>

Main container

The main container is the main wrapper that consists of product containers. It is a <div> type HTML element with the class name "ins-preview-wrapper-{variationId}". 

<div class="ins-preview-wrapper-{variationId}">

For this class, it is enough to add it to the template for once, you should take the variationId from the event data object as shown below;

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) { 
    const variationId = data.variationId; 
});

The "ins-preview-wrapper" is followed by the variation ID. For example, the main container of a variation whose ID is 1 is as follows:

<div class="ins-preview-wrapper-1"></div>

Body Container

The body container has data-recommended items. It is one of the child elements of the main container, and the main wrapper of product boxes. It is a <div> type HTML element that has the specific attribute "data-recommended-items". The attribute value is an array of string product IDs. For example, the HTML element of a campaign with four recommended products with IDs 111, 222, 333, and 444 is as follows:

<div class=”ins-web-smart-recommender-body” data-recommended-items="["111", "222", "333","444"]"></div>

Also, it is enough to add this class to the template for once and you have an attribute that you should add to the same element with the class you add. Below is the type of data-recommended-items as a stringified array.

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) { 
    var productIds = [];

    data.products.forEach(function(product) {
        productIds.push(product.item_id);
    });

   Var stringifiedProductIds = JSON.stringify(productIds);
});

Product container

Product container is one of the child elements of the products container, and the main wrapper of the products. It is a <div> type HTML element. Inside each product container, you need to add the class below:

<div class="ins-web-smart-recommender-box-item">

After you add this class, you can contain multiple products on a product container. With this HTML element, you don’t need to perform any dynamic replacements.

For example, the HTML element of a campaign with two recommended products is as follows:

<div class="ins-web-smart-recommender-box-item">

            <div class="ins-product-box ins-element-link ins-add-to-cart-wrapper ins-sr-api" ins-product-id="{product's id}" event-collection="true"></div>
</div>

Product Box

The product box contains Product ID attribute and Event Collection attribute. It is one of the child elements of the product container, and the main wrapper of the products. It is a <div> type HTML element.

<div class="ins-product-box ins-element-link ins-add-to-cart-wrapper ins-sr-api" ins-product-id="{product's id}" event-collection="true">

You also need to add those IDs and attributes to each product container; 

• A custom attribute named event-collection which always has the value of true
• The class attribute has the value "Ins-product-id". For each product, you should get the ID from the event payload and inject it here.

Once you complete creating the HTML design, you can insert it into your web pages where you want to display your campaign.

Mobile Web Template

Mobile Web template has 2 different classes that differ from the Desktop Template:

<div class="ins-mobile-web-smart-recommender-body" data-recommended-items="["{product1\'s id}",' +' "{product1\'s id}", "{product1\'s id}", ...>">

<div class="ins-mobile-web-smart-recommender-box-item">

A complete Visual Mobile Web Smart Recommender HTML with all elements looks like:

<div class="ins-preview-wrapper-{variationId}">
   <div class="ins-mobile-web-smart-recommender-body" data-recommended-items="["{productId1}",' +' "{productId2}", "{productId3}", ...>">
       <div class="ins-mobile-web-smart-recommender-box-item">
           <div class="ins-product-box ins-element-link ins-add-to-cart-wrapper ins-sr-api" ins-product-id="{product's id}" event-collection="true"></div>
       </div>
   </div>
</div>

Simple Smart Recommender Widget Example

In the below example, self triggered function is used. First, set the data object to a global variable; 

Insider.eventManager.once('ins-sr:only-api-campaign:load', function (event, data) {
   window.recommendationData = data;
});

Sample HTML Widget Implementation Code

(function (){
   var { variationId, campaignId, products } = window.recommendationData;
   var partnerCurrency = Insider.systemRules.call('getCurrency');
   var stringifiedProductIds;
   var self = {};
  
   self.init = function() {
       self.reset();
       self.createProductsHtml();
       self.prepareDataRecommendedItems();
       self.createRecommendationWidget();
   };

   self.reset = function() {
       Insider.dom('.recommendation-widget').remove();
   };

   self.prepareDataRecommendedItems = function() {
       var productIds = [];

       products.forEach(function(product) {
           productIds.push(product.item_id);
       });
  
      stringifiedProductIds = JSON.stringify(productIds);
   };

   self.createRecommendationWidget = function() {
       var productHtml = self.createProductsHtml();
       var recommendationWidget =
       '<div class="recommendation-widget ins-preview-wrapper-' + variationId + '"> ' +
       '   <div class="header">recommendation header</div>' +
       '   <div class="recommendation-body ins-web-smart-recommender-body" data-recommended-items=' + stringifiedProductIds + '>' +
               productHtml +
       '   </div>' +
       '</div>';

       Insider.dom('body').append(recommendationWidget);
   };

   self.createProductsHtml = function() {
       var html = '';

       products.forEach(function(product) {
           html +=
               '<a class="product-outer-box ins-web-smart-recommender-box-item" href="' + product.url + '">' +
               '   <div class="product-inner-box ins-product-box ins-element-link ins-add-to-cart-wrapper ins-sr-api" ins-product-id="'+ product.item_id +'" event-collection="true">' +
               '       <div class="product-image" style="background-image: url(' + product.image_url + ');"></div>' +
               '       <div class="product-name">' + product.name + '</div>' +
               '       <div class="product-price">' + product.price[partnerCurrency] + '</div>' +
               '   </div>' +
               '</a>'
               });

       return html;
   };

   return self.init();
})();

CSS

.recommendation-widget {
   position: absolute;
   top: 20%;
   width: 100%;
   height: 425px;
   background: wheat;
}

.header {
   text-align: center;
   font-size: 20px;
   padding-top: 10px;
}

.recommendation-body {
   display: inline-block;
   width: 100%;
   height: 80%;
   overflow: hidden;
}

.product-outer-box {
   width: 20%;
   height: 100%;
   display: block;
   float: left;
}

.product-inner-box {
   height: 100%;
   width: 100%;
}

.product-image {
   height: 70%;
   width: 100%;
   background-repeat: no-repeat;
   background-size: contain;
}

.product-name, .product-price {
   text-align: center;
   color: white;
   padding-top: 20px;
}

Notes

• If multiple campaigns are available, the events of different campaigns can be differentiated by condition blocks depending on “campaignId”. You can check your campaign IDs from the InOne panel.
• Some algorithms due to training times or insufficient data recommendation generation might be delayed. When recommendations are not ready, subscribed events do not trigger.
• To integrate and test the API-based Smart Recommender, you need to create and activate a campaign. You can also view the integration details in the Launch step or for each campaign using the Requirements button on the campaign list page.