Loading...
Area: Episerver Commerce, Episerver Product Recommendations
Applies to versions: EPiServer.Personalization.Commerce 1.0 and higher

Recommendations client side API integration

Recommendations [hide]

Note: Sample code in this article is taken from Quicksilver templates. The Quicksilver Commerce sample site and installation instructions are available for download from GitHub.

This document explains how to integrate Recommendations client-side API for an Episerver based website.

In this topic

Preparation

See Episerver Recommendations API: An overview for the initialization steps. Then, continue with the steps below.

1. Define the recommended sections

In the Views/Shared/_Layout.cshtml view, add following sections:

  • recommendations-upper
  • recommendations-left
  • recommendations-right
  • recommendations-bottom

Example:

...
<div class="main-area">@RenderBody()</div>
  <div class="recommendations recommendations-upper"></div>
  <div class="recommendations recommendations-left"></div>
  <div class="recommendations recommendations-right"></div>
  <div class="recommendations recommendations-bottom"></div>
</div>
...

2. Add the client-side tracking script

To the Views/Shared/_Layout.cshtml view, add following @using statement to the top of file.

@using EPiServer.Personalization.Commerce.Extensions

Then, add @Html.LoadTrackingAPI() to the <HEAD> tag, like this.

...
<head>
  ...
  @Html.LoadTrackingAPI()
</head>
...

3.  Set up the template engine to render recommended data

This section provides an example of using the mustache.js template engine to render recommended data. The following code resides inside a partial view named Views/Shared/_RecommendationsTemplates.cshtml.

<script id="epiRecommendationListTemplate" type="x-tmpl-mustache">
  {{#recs}}
    <div class="jsProductTile product-row__tile" data-recommendation-id="{{id}}">
      {{> epiRecommendationItemTemplate}}
    </div>
  {{/recs}}
</script>

<script id="epiRecommendationItemTemplate" type="x-tmpl-mustache"> 
  {{#hasDiscount}}
    <div class="product has-discount">
  {{/hasDiscount}} 
    {{^hasDiscount}}
      <div class="product">
    {{/hasDiscount}} 
      <a href="{{#attributes}}{{url}}{{/attributes}}&recommendationId={{id}}" class="link--black"> 
        <div class="view-details"></div> 
        <img src="{{#attributes}}{{img}}{{/attributes}}" alt="{{refCode}}" class="img-responsive" /> 
        <h3 class="product-title">{{#attributes}}{{title}}{{/attributes}}</h3> 
        <div> 
          {{#hasDiscount}}
            <h4 class="product-price">{{#attributes}}{{unitPrice}}{{/attributes}}</h4> 
            <h4 class="product-price product-price--discount">{{#attributes}}{{salePrice}}{{/attributes}}</h4>
          {{/hasDiscount}} 
          {{^hasDiscount}}
            <h4 class="product-price">{{#attributes}}{{salePrice}}{{/attributes}}</h4>
          {{/hasDiscount}}
        </div>
      </a>
    </div>
  </div>
  <div class="quick-view-btn-container">
    <button type="button" 
            data-toggle="modal" 
            data-target="#ModalDialog"
            data-url="{{#attributes}}{{url}}{{/attributes}}&recommendationId={{id}}"
            class="btn btn-block btn-sm quickview-button">@Html.Translate("/Product/Quickview")
    </button>
  </div>
</script>

4. Render recommendation templates

In the Views/Shared/_Layout.cshtml view, render the templates created in step 3.

<body>
  ...
  @Html.Partial("_RecommendationsTemplates")
  ...
</body>

5. Render the page tracking script

To the Views/Shared/_Layout.cshtml view, add following code to render the page tracking script.

@RenderSection("Tracking", false)

After that, the page should look like this.

<body>
  ...
  @Html.Partial("_RecommendationsTemplates")
  @RenderSection("Tracking", false)
</body>

Track with custom attributes

This section explains how to create, send, then consume recommendations on a page with custom attributes. This integration is applied to a Product package page.

1. Create product tracking data

var refCode = '@Model.Package.Code';
var packageTrackingData = TrackingDataFactory.createProductTrackingData(refCode);

2. Add a custom attribute

packageTrackingData["customAttributes"] = { 'marketId': Market.getSelectedMarketId() };

3. Send a tracking request and receive recommendations

epiRecommendations.track(
  packageTrackingData, 
  null, 
  Recommendations.render, 
  { sectionMappings: 
    [
      { area: "productAlternativesWidget", selector: ".recommendations-right", numberOfItemsToRender: 2 }, 
      { area: "productCrossSellsWidget", selector: ".recommendations-bottom" }
    ]
  });

In the view Views/Packages/Index.cshtml, use these settings to render more than one recommendation section.

@section Tracking
  {
    <script>
      $(document).ready(function () {
        var refCode = '@Model.Package.Code';
        var packageTrackingData = TrackingDataFactory.createProductTrackingData(refCode);
        packageTrackingData["customAttributes"] = { 'marketId': Market.getSelectedMarketId() };
        epiRecommendations.track(
          packageTrackingData, 
          null, 
          Recommendations.render, 
          { sectionMappings: [
            { area: "productAlternativesWidget", selector: ".recommendations-right", numberOfItemsToRender: 2 }, 
            { area: "productCrossSellsWidget", selector: ".recommendations-bottom" }
          ]});
      });
    </script>
  }

The section mapping defines options to render the recommended data.

  • The first section mapping:
    • Type of productAlternativesWidget 
    • Maximum items are 2
    • The HTML tag with the CSS class is recommendations-right
  • The second section mapping:
    • Type of productCrossSellsWidget  
    • No maximum
    • The HTML tag with the CSS class is recommendations-bottom
Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 08, 2017

Recommendations [hide]