Client-side API integration

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

Preparation

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

📘Note

Preparation

1. Define the recommended sections

2. Add the client-side tracking script

3. Set up the template engine to render recommended data

4. Render recommendation templates

5. Render the page tracking script

Track with custom attributes

1. Create product tracking data

2. Add a custom attribute

3. Send a tracking request and receive recommendations

📘
Note