Client-side API integration

7 min

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

See Commerce Connect API overviewCommerce Connect API overview for the initialization steps.

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

...
<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>
...

Add the client-side tracking script. In the Views/Shared/_Layout.cshtml view, add the following @using statement to the top of the file.

@using EPiServer.Personalization.Commerce.Extensions

Then add @Html.LoadTrackingAPI() to the <head> tag:

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

Set up the template engine to render recommended data. This example uses the mustache.js template engine. The following code resides in 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 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>

Render recommendation templates. In the Views/Shared/_Layout.cshtml view, render the templates you created:

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

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

@RenderSection("Tracking", false)

The page now looks like the following:

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

Track with custom attributes

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

Create product tracking data:

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

Add a custom attribute:

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

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 Views/Packages/Index.cshtml view, 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:

First section mapping:

Type: productAlternativesWidget

Maximum items: 2

Target HTML element with CSS class recommendations-right

Second section mapping:

Type: productCrossSellsWidget

Maximum items: none

Target HTML element with CSS class recommendations-bottom