Client-side API integration

12 min

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

Preparation

See Customized Commerce API overviewCustomized Commerce API 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. Configure 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