HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Client-side API integration

Describes how to integrate Optimizely Product Recommendations client-side API to Optimizely Commerce (PaaS).

📘

Note

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

Preparation

See Commerce (PaaS) 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