Browser Facing Recommendations

This document describes how to instruct Browsers to obtain recommendations from ShiftForward DMP and integrate them with other advertising or e-commerce platforms.

1st vs. 3rd party domain

If you’re set up under your own domain, replace the shiftforward.io domain with your own custom domain in the tags below or contact ShiftForward support for assistance.

Javascript Library

This method allows using JSONP to request a recommendation for a user and then handle it using a custom callback javascript function. It uses the Javascript Recommendations library.

Including the library

The recommendation library is the same used for tracking and it should only be included once in the page. If already present, you can skip this step. To use the library, you should insert the following code at the end of your HTML head:

<!-- ADSTAX Tag -->
<script type="text/javascript">
 // optional - custom options
 var _adstaxOptions = _adstaxOptions || {};
 _adstaxOptions.trackingHost=""; // a custom tracking domain
 // end optional

 (function() {
   var adstax = document.createElement("script"); adstax.type = "text/javascript"; adstax.async = true;
   var host = "sfwd.io";
   adstax.src = ("https:" == document.location.protocol ? "https://" : "http://") + host + "/adstaxtag_3.0.js";
   var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(adstax, s);
 })();
</script>
<!-- End of ADSTAX Tag -->

Requesting Recommendations

The library provides a push function that handles a dictionary with your client and site Ids and a callback function name to be called with the response. The callback can be configured as follows:

<script type="text/javascript">
function processRecommendation(recommendation_object) {
  console.log("Recommendations or null: " + recommendation_object);
}

var _adstaxRec = _adstaxRec || [];
_adstaxRec.push({
  clientId: "0",
  siteId: "0",
  callback: "processRecommendation"
});
</script>

All users are segmented server-side for A/B testing, enabling a continuous evaluation of the uplift provided by ShiftForward DMP recommendations.

Recommendations are always specific for the browser, clientID and siteID from where the request is issued. When the user isn’t considered, the callback function will be invoked with a single parameter with value of null. On success, the callback function will be invoked with a single parameter with an object containing the following fields:

  • recommendedProducts – An array of integers with the id of each recommended product.
  • timestamp – A string with the time stamp of when the recommendation was created.

Example:

{
  "recommendedProducts": [
    "74110",
    "175832",
    "264107",
    "206444",
    "110688"
  ],
  "timestamp": "2015-10-09T14:03:36.349Z"
}

Integrate using redirections

This method requires a small change to existing ad/creative tags that instructs the Browser to first fetch a recommendation and then follow to the ad/creative with the proper product id included.

It uses the HTTP 302 status code redirection method and accepts a redirection URL with dynamic variables to be replaced with recommended product ids.

Redirect interface description

Base template url

https://.../recommendations/redirect?pidparam=<productRcmdMacro>&clientId=<clientId>&siteId=<siteId>&ourlenc=<urlEncTimes>&ourl=<oUrl>

Parameters

  • productRcmdMacro: the string in the destination url to be replaced by comma-separated recommended product ids, e.g. PRODUCT_ID.
  • clientId: the id of the client in ShiftForward DMP.
  • siteId: the id of the site in ShiftForward DMP. The clientId combined with siteId identify which set of products to recommend from.
  • urlEncTimes: how many times the destination URL has been URL-encoded, e.g. 0.
  • oUrl: the redirection url to follow, url-encoded urlEncTimes times, which includes the product id macro productRcmdMacro to be replaced by recommended product id(s).

Example iFrame tag

Original iFrame tag for clientId “LargeRetailer” for its siteId “BestSalesGoods.com”:

<iframe id="1234" src="//creatives.adserverdomain.com?param1=abc&m2=def&campaign=xmas2014&productId={product_id_to_display}&clickTag=%%CLICK_URL_ESC%%" width="160" height="600" marginwidth="0" marginheight="0" frameborder="no" scrolling="no"></iframe>

Amended iFrame tag with product recommendations:

<iframe id="1234" src="//recommendations.shiftforward.io/recommendations/redirect?pidparam=%%PRODUCT_ID%%&clientId=LargeRetailer&siteId=BestSalesGoods.com&ourlenc=0&ourl=http://creatives.adserverdomain.com?param1=abc&m2=def&campaign=xmas2014&productId=%%PRODUCT_ID%%&clickTag=%%CLICK_URL_ESC%%" width="160" height="600" marginwidth="0" marginheight="0" frameborder="no" scrolling="no"></iframe>

Notice the clientId and siteId which represent the client and site for getting the appropriate recommendations for.

%%PRODUCT_ID%% is the macro for the product id(s) recommended. The interface takes it as a parameter and looks for it in the destination url (also in bold above). You can replace the default %%PRODUCT_ID%% with something else if required.

Integrate using JSONP

This method allows using JSONP to request data and process it with a custom callback. It makes use of the /recommendations/user endpoint with an extra callback parameter with the name of the JavaScript function to be called. In the following examples, <clientId> refers to the id of the client in ShiftForward DMP and <siteId> refers to the id of the site in ShiftForward DMP. The clientId combined with siteId identify which set of products to recommend from.

Vanilla JavaScript with request in script src

<html>
  <head>
  </head>
  <body>
    <h1>JSON Result</h1>
    <ul id="result">
    </ul>

    <script type="text/javascript">
     function append(data, status) {
       var json = "recommendation not found";
       console.log('Received status: ' + status);
       if (status == 200) {
         json = JSON.stringify(data);
         console.log('Received json: ' + json);
       }

       var list = document.getElementById('result');
       var entry = document.createElement('li');
       entry.appendChild(document.createTextNode(json));
       list.appendChild(entry);
     };
     // Async Script injection
     var script_element = document.createElement("script");
     script_element.src = "//recommendations.shiftforward.io/recommendations/user?clientId=<clientId>&siteId=<siteId>&callback=append"
     document.getElementsByTagName("head")[0].appendChild(script_element);
    </script>
  </body>
</html>

Vanilla JavaScript with dynamically built request

<html>
  <head>
  </head>
  <body>
    <h1>JSON Result</h1>
    <ul id="result">
    </ul>

    <script type="text/javascript">
      var clientId = "<clientId>";
      var siteId = "<siteId>";
      var callback = "append";

     (function() {
       var script = document.createElement('script');
       script.type = 'text/javascript';
       script.src = 'http://recommendations.shiftforward.io/recommendations/user?clientId=' + clientId + '&siteId=' + siteId + '&callback=' + callback;
       document.head.appendChild(script);
     })();

     function append(data, status) {
       var json = "recommendation not found";
       console.log('Received status: ' + status);
       if (status == 200) {
         json = JSON.stringify(data);
         console.log('Received json: ' + json);
       }

       var list = document.getElementById('result');
       var entry = document.createElement('li');
       entry.appendChild(document.createTextNode(json));
       list.appendChild(entry);
     };
    </script>
  </body>
</html>

jQuery

<html>
  <head>
  </head>
  <body>
    <h1>JSON Result</h1>
    <ul id="result">
    </ul>

    <script src="//code.jquery.com/jquery-1.11.1.min.js"></script>
    <script type="text/javascript">
      var clientId = "<clientId>";
      var siteId = "<siteId>";

      (function() {
        var adstaxApi = 'http://recommendations.shiftforward.io/recommendations/user?clientId=' + clientId + '&siteId=' + siteId + '&callback=?';
        $.getJSON(adstaxApi).done(function(data) {
          var json = "recommendation not found";
          if (typeof data != 'undefined') {
            json = JSON.stringify(data);
            console.log('Received json: ' + json);
          }

          $('#result').append('<li>' + json + '</li>');
        });
      })();
    </script>
  </body>
</html>