Shopper Ratings - Advanced Content Integration Guide

August 2015

Confidential

© Webcollage, Inc., an Answers company

Contents

  1. Introduction
  2. Controlling the timing of content load
  3. Integrating test content on test sites
  4. Controlling which form factor the content is optimized for
  5. Adding content to dynamic pages
  6. Placing the content in a container other than the default
  7. Resizing the container to accommodate the additional content
  8. Allocating a special tab for the content
  9. Reporting when content is available
  10. Activating Interactive Product Image
  11. Advanced API
  12. Backward compatibility
1. Introduction

Webcollage Power Page API and the service it provides is one part of a more comprehensive set of services provided by the Answers platform. You can incorporate all Answers services into your HTML page by adding a simple snippet of JavaScript code to your page. In this document, we describe the JavaScript snippet, but mainly focus on the Power Page API.

This document explains how to use the Webcollage Power Page API to control how content is added to product detail pages. Specifically, this document provides details and examples for several scenarios:

  • Controlling the timing for loading the content
  • Integrating test content on test sites
  • Controlling which form factor the content is optimized for
  • Adding the content to dynamic product detail pages, such as pages with tabbed navigation
  • Adapting the product detail page to accommodate the content
  • Emitting reporting events when the content is loaded

Note: In Webcollage terms, a Power Page is the HTML section embedded into the product detail page.

Embedding the Answers Code Snippet into Your Page

In order to enable the Power Page API on your page you must first add the Answers code snippet to your page. The Answers code snippet is as follows:

<script type="text/javascript">//
// Instructions: please embed this snippet directly into every page in your website
// template. For optimal performance, this must be embedded directly into the template,
// not referenced as an external file.
// Answers Embed Script v1.01
// DO NOT MODIFY BELOW THIS LINE *****************************************
;(function (g) {
   var d = document, i, am = d.createElement('script'),
      h = d.head || d.getElementsByTagName("head")[0],
         aex = {
           "src": "//gateway.answerscloud.com//production/gateway.min.js",
           "type": "text/javascript",
           "async": "true",
           "data-vendor": "acs",
           "data-role": "gateway"
         };
   for (var attr in aex) { am[attr] = aex[attr]; }
   h.appendChild(am);
   g['acsReady'] = function () {var aT = '__acsReady__', args = Array.prototype.slice.call(arguments, 0),k = setInterval(function () {if (typeof g[aT] === 'function') {clearInterval(k);for (i = 0; i < args.length; i++) {g[aT].call(g, function(fn) { return function() { setTimeout(fn, 1) };}(args[i]));}}}, 50);}; })(window); // DO NOT MODIFY ABOVE THIS LINE ***************************************** // ]]></script>

Just copy and paste the code snippet into your page and replace <site-code> with the retailer ID provided to you by Webcollage.

This code snippet loads to your page the Answers services that are configured for it, in our case the Power Page service API. The API code is loaded asynchronously, which means it loads in the background and has minimal effect on the load time of your page. The asynchronous nature of the API load also means that you cannot call the API immediately after the code snippet, as it may not be available yet. Instead, you need to register a callback function that will call the API once it’s available. To register the callback function you should use the acsReady method, which is defined in the code snippet above. For example, instead of calling:

Webcollage.loadContent(...);

Register a callback that calls it:

acsReady(function(){
   Webcollage.loadContent(...);
});

Now for the actual API…

Understanding the Basic Webcollage API

In preparation to adding the Power Page content to your product page you need to:

  1. Add a container element to the product detail page template in the location where you want the Power Page content to appear. The Power Page content populates this container element. By default, Webcollage recommends to assign the container element with ID wc-power-page. If you use this id the system automatically finds the container. Otherwise you must provide a selector to it when calling the Power Page API. An example of such element is:
    <div id="wc-power-page"></div>

    Important: The Power Page content added to your page contains, among others, HTML block element. This means that your container element should also be a block element or it may confuse the browser. This is because, in HTML, line elements should not contain a block element. Our recommendation is to use a div element for the container.

  2. Call the Webcollage API that integrates the Power Page content into the container. To do this you should first add the Answers code snippet into your page as explained in the previous section. Then add a call to the loadContent method that performs the injection:
    <script>
       acsReady(function(){
          Webcollage.loadContent("<site-code>", "<product-id>");
       });
    </script>

    The two arguments to the loadContent call are:

    • site-code: The code that identifies the retailer. This is the unique string provided by Webcollage to identify the retailer. Put your retailer ID as this argument in all product detail pages.
    • product-id: This is the unique identifier the retailer uses to identify the product, (a.k.a., product number, item number) and is usually part of the URL on the retailer website. Include the product-id for the specific product in each product detail page.

Note: The Webcollage content is injected into the container div and replaces any content that was previously inside it. Thus if you have content you wish to replace with content from Webcollage put it inside the container element. If you wish to keep your content alongside the Webcollage content, put it in another element and keep the container div empty.

2. Controlling the timing of content load

The Answers API, which includes the Webcollage Power Page API is an asynchronously loaded JavaScript code. This means that the loading of the API code should not interfere with your page’s load time nor delay it. However, sometimes, due to your own design consideration, you must control the timing of the actual injection action. For example, if you create the container element dynamically you must delay the injection operation until after the container is ready in the DOM of the page.

The timing of the injection operation is mainly determined by the timing of the call to Webcollage.loadContent. So if, for instance you want to defer the Power Page injection until after the page is completely loaded you should call loadContent in the onload method of your page:

window.onload = function () {
   acsReady(function(){
      Webcollage.loadContent("<site-code>", "<product-id>");
   });
}

Similarly, you may use jQuery’s ready callback to inject the content once the DOM is fully constructed:

$(document).ready( function () {
   acsReady(function(){
      Webcollage.loadContent("<site-code>", "<product-id>");
   });
});
3. Integrating test content on test sites

As Webcollage content is loaded, an additional options argument can be passed to the Webcollage.loadContent call. This argument is a JavaScript object specifying a set of parameters.

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", options);
});

The parameter used by the Webcollage system to control whether the content served is live content or test content is testMode. When this parameter is set to true, the Webcollage system returns test content specifically created and optimized for test sites and test scenarios.

By default, the content that the Webcollage system returns is determined based on the settings in the Webcollage Content Publisher GUI. It starts by displaying test content. Then, when the system is switched to live mode, the system starts returning live content.

If you’d like to continue using the test content on your test site, you can use the testMode parameter to control the behavior.

To do this, use this code on your test site:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {testMode: true});
});

And, use the following code on your production site:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {testMode: false});
});

Alternatively, this can be simplified. For example, if your production site is www.acme.com, you can use the following code to show test content on all non-production sites:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {testMode: (window.location.hostname ! = 'www.acme.com')});
});
4. Controlling which form factor the content is optimized for

As Webcollage content is loaded, it examines the user’s browser (a.k.a., user agent) and the page characteristics (e.g., width) to determine the form factor (computer, tablet or phone) to which to optimize the content’s layout.

If as part of the product detail page code you already analyze the user agent and determine which form factor is used, you can pass this data to the API. This ensures that the layout is optimized to the same form factor to which the content itself is optimized.

To do this, pass a layout parameter. The layout can be one of three values: computer, tablet or phone.

For example,

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {layout: "computer"});
});
5. Adding content to dynamic pages

In some cases, the product detail page is built, or modified dynamically. Two common cases for this scenario are:

  • The site displays the content only when a shopper performs a certain action, such as clicking on a tab.
  • The site’s HTML code is authored to assemble the page dynamically during loading using JavaScript and Dynamic HTML.

During initialization, the Webcollage content calculates its dimensions and adds HTML objects to the page. If your site assembles the product detail pages dynamically, the content cannot reliably initialize before its container area is available and visible. The system has a built-in mechanism that automatically detects when the content is visible. This mechanism relies on the calculated style of the content as defined in http://api.jquery.com/visible-selector/. As soon as the content becomes visible, this mechanism activates the content automatically.

To turn on the auto-start mechanism you must pass true in the autoPlayAndStop option:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {autoPlayAndStop: true});
});

If the mechanism you use to show and hide the PP content does not comply with http://api.jquery.com/visible-selector/ please refer to “Advanced API” below, specifically to playPowerPage and stopPowerPage.

6. Placing the content in a container other than the default

If, for some reason, you cannot assign the element that contains the content with the ID “wc-power-page”, you may override this default by using the containerSelector option. You can use this option to pass a jQuery selector to the DOM element where you want the content placed by the system.

For example:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>",
               {containerSelector: "ul.manufacturer>li:first"});
});

This places the content in the first li of the ul with class manufacturer.

7. Resizing the container to accommodate the additional content

In some cases, the element that contains the content is of a fixed size (width and height). In such cases, adding the manufacturer content to the container may cause the content to overflow outside the container. In order to avoid this behavior you can pass, a resizeCallback function. The system calls the resizeCallback function whenever the content changes its size. This allows you to adjust the size of the container accordingly.

For example:

function adjustContainer (width, height) {
               myContainer.resize(width, height + 5);
}
acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {resizeCallback: adjustContainer});
});

In this case, the adjustContainer method is called by the system whenever the content changes its size with the new width and height of the content. The function, then, changes the size of the container to a similar size with an additional five pixels at the bottom to leave a little space from the next section.

Important: Due to the dynamic nature of the PP content it may change its size during user interaction (e.g., playing an interactive tour will extend the height of the content), thus the adjustContainer method must be ready to be called more than one time during initialization.

8. Allocating a special tab for the content

If you want to put the Webcollage content in a tab allocated just for the content (i.e., the tab will not show for products that do not have PP content available), you need to know if there is content available for the product in order to create the tab. To do this, you can pass a hasPowerPageContentCallback callback function in the options. The system calls this function only if there is content available for the product and the call is done just prior to the injection of the content. You should use this function in order to create the container tab.

For example:

function createManufacturerTab () {
   tabSystem.createTab("From the Manufacturer");
}
acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>",
               {hasPowerPageContentCallback: createManufacturerTab,
               autoPlayAndStop: true});
});

In this case createManufacturerTab is called when content is available and it creates a new tab titled “From the Manufacturer” into which the content is injected.

9. Reporting when content is available

As shown above, you can provide a callback function that is called when content is available for the current product. You can use the same callback to trigger a reporting event that reports the existence of manufacturer content on the page:

function reportManufacturerContent (theContent) {
   someReportingTool.someReporting(someParameters); // Example only
}
acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>",
               {hasPowerPageContentCallback: reportManufacturerContent});
});
10. Activating Interactive Product Image

Starting in 2015, Webcollage introduced a feature for products that have Interactive Product Tour content: Interactive Product Image (IPI). This feature allows presenting the Interactive Product Tour hotspots on the main product image of the product page and zooming into the hotspot description when the user clicks the hotspot.

To present the Interactive Product Tour hotspots on your product image simply add the class wc-InteractiveProductImage to the image you choose and, if there is an Interactive Product Tour associated with the product, the system will automatically add the hotspots to the image with that class.

For example:

<img src="main-product-image.png"> class="wc-InteractiveProductImage"

Will add hotspots to the image main-product-image.png as long as it is visible on the page.

Gaining Better Control over IPI Presentation

Instead of adding the class wc-InteractiveProductImage, you can use the Webcollage API to inject the Interactive Product Tour images to your product image. The following code sample adds product hotspot to the main product image on the page, which is located in an img element with id ‘mainImage’:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", {
      ipiReadyToInject : function(ipiCandidates){
         var $ = Webcollage.jQuery
         var $imageElement = $("img#mainImage");
         if ($imageElemnt.length) {
            $imageElemnt[0].src = ipiCandidates[0].image.src;
            return {
               zIndex : 100,
               maxHotspots : 5,
               candidateIndex : 0,
               image : {
                  element : $imageElement[0],
                  src : ipiCandidates[0].image.src
               }
            };
         }
      }
   });
});

This code also replaces the main product image on the page with the main image of the Interactive Product Tour.

Explanation:

The new data field ipiReadyToInject added to the options parameter of Webcollage.loadContent, is pointing to a callback function. The Webcollage system calls the ipiReadyToInject callback during page load if there is IPI content ready on the page.

When calling the ipiReadyToInject callback function, the Webcollage system passes one parameter – ipiCandidates to it, which is an array of IPI candidate structures, each structure in the array contains the following data fields:

  • hotspotsCount: the number of hotspots available for the candidate
  • sectionCaption: the caption of the Interactive Product Tour section
  • image: the details of the Interactive Product Tour main image – you can use it in order to either replace your product image or add it to the images carousel so that the hotspots will match the image better. The image details contain the following fields:
    • width: image width in pixels
    • height: image height in pixels
    • src: image source URL (absolute URL)

The Webcollage system expects the ipiReadyToInject callback function to return a structure with the following fields:

  • candidateIndex: optional, default value=0, this numeric field selects which one of the candidate Interactive Product Tours should be used for the IPI. This field is an index into the ipiCandidates array passed to ipiReadyToInject. If this field contains an invalid index to the ipiCandidates array, the system calls the callback function ipiDataError (see below) to report the error.
  • maxHotspots: optional, default value=maxInt, this numeric field limits the number of hotspots to present on the product image, if not provided all hotspots will be displayed
  • zIndex: optional, default=auto, the zIndex that Webcollage system should use to locate the hotspots on the page
  • image: mandatory, a structure containing information about the image that will receive the IPI hotspots. This structure contains the following data fields:
    • element: mandatory, the element in the DOM of the image to receive the hotspot
    • src: optional, no default, if presented it means that only if the src attribute of the element above is equal to src the hotspots are shown and whenever the src changes the hotspots disappear. This is for cases where the image carousel replaces the src of the main image. If not presented that means that the carousel replaces the active image element.

In addition to the ipiReadyToInject callback function, you can pass the following data fields, in the options parameter of Webcollage.loadContent:

  • ipiDataError: a callback function that is called in case of an error in the ipiReadyToInject response the ipiDataError callback receives a structure with two data fields: candidateIndex – the index of the candidate that was selected and message – the text description of the problem.
  • ipiInjected: is called when the IPI content injection is done
  • ipiHotspotHide: is called when the system hides the IPI content
  • ipiHotspotShow: is called when the system shows the IPI content

In addition, you can call the following Webcollage methods to hide / show the IPI content:

  • Webcolage.showIPI – to show the IPI content
  • Webcolage.hideIPI – to hide the IPI content
Combining the wc-InteractiveProductImage class and the Webcollage API

Adding the class wc-InteractiveProductImage to your image is equivalent to providing ipiReadyToInject callback that returns:

{
   candidateIndex : "0",
   image : {
      element : _wcjq(".img.wc-InteractiveProductImage")[0]
   }
}

All other values are set to their defaults. However, you can combine the two methods by adding the class wc-InteractiveProductImage to your image and providing an ipiReadyToInject callback. In such case, the ipiReadyToInject callback only needs to return any field that you wish to override. For example, the following code:

<img src="main-product-image.png" class="wc-InteractiveProductImage" >
...
<script>// <![CDATA[
acsReady(function(){
    Webcollage.loadContent("<site-code>", "<product-id>", {
      ipiReadyToInject : function(ipiCandidates){
        return {
          zIndex : 200,
        };
      }
    });
  });
// ]]></script>

Instructs the system to inject hotspots, if available, to the main-product-image.png image and position them on zindex 200.

11. Advanced API

The Webcollage objects provide a few additional methods that you can use to gain better control over the activation of the content in your page or to handle cases that the default system behavior cannot handle. The list of additional methods is as follows:

Method Action
playPowerPage Activates the interactive parts of the Power Page (e.g., sets up the video player)
stopPowerPage Deactivates the interactive parts (e.g., stops playing videos) of the Power Page
checkContentPlayStop Automatically detects the status of the Power Page (displayed or not) and activate or deactivates it accordingly
terminatePowerPage Terminates all activity associated with a Power Page – this method should only be called if you already have Power Page content on your page and you want to replace it with different Power Page content.

Below are details for using the four methods provided by Webcollage:

  • playPowerPage ()

    The playPowerPage function activates the Power Page content on the page. This function builds all the active elements in the Power Page content such, as video players for video galleries, or document viewers for document galleries, etc. It also computes the dimensions of the content and adjusts the layout accordingly. You should use this method if your system uses tabs and the mechanism to hide/show the tab’s content does not comply with http://api.jquery.com/visible-selector/. In such a case you should hook to the tab switch event and call playPowerPage whenever the tab containing the content becomes visible and stopPowerPage (see below), whenever the tab becomes invisible.

  • stopPowerPage ()

    The stopPowerPage function deactivates the Power Page content, which stops videos, hides overlays and terminates all other interactive elements.

    This function should be called when the content becomes invisible following a shopper action. For example, the shopper navigates to a different tab on the page.

  • checkContentPlayStop ()

    The checkContentPlayStop function checks for transitions in the visibility status of the Power Page content and upon a transition from visible to invisible calls stopPowerPage. While on transition from invisible to visible, it calls playPowerPage.

    This function should be called whenever a click is detected on any of the product page tabs to determine whether to stop or play the Power Page content in response to a tab click. Setting autoPlayAndStop to true in the initPowerPage options parameter causes this function to be called automatically on a regular basis (every 0.2 seconds).

    Note: Do not use this function if the method your tabbing system uses to show and hide tabs does not conform with the jQuery :visible selector (see: http://api.jquery.com/visible-selector/). In such a case, use playPowerPage and stopPowerPage.

  • terminatePowerPage ()

    This method terminates the active components of a Power Page in a way that allows you to safely remove it from your page and, possibly, inject different Power Page content into your page. The method is seldom required and is only called in cases where the same page can switch between two different sets of content (e.g., dynamically switching from a red camera to a blue camera, resulting in different content). In such cases, before switching to the new product, call terminatePowerPage for the current product. Then reload and reactivate the new product’s content.

Other Members of the Webcollage object

Webcollage has the following member:

  • jQuery (and a shorthand, $)

    Includes the Webcollage version of the jQuery library. In case the container page does not utilize the jQuery library, it may use this object to easily manipulate the page for controlling the content.

12. Backward compatibility

For backward compatibility reasons the system still supports passing a forth parameter to loadContent in the form:

acsReady(function(){
   Webcollage.loadContent("<site-code>", "<product-id>", options, contentLoadedCallback);
});

Although the system still supports using this method, it is not recommended as it is deprecated and will be removed in the future.

If you pass this callback to the system, the system calls it to activate the content instead of using the default activation behavior. This, combined with a set of additional Webcollage methods, allows you to override the default Power Page injection and activation mechanism.

To activate the content the contentLoadedCallback callback function should call initPowerPage, which initializes the content as described below.

Example 1: Built-in behavior

The sample below shows the built-in behavior. In this case, the container site initializes the Power Page as it is ready and activates the interactive elements.

function contentLoadedCallback (theContent) {
   Webcollage.$(function() {
      Webcollage.initPowerPage("#wc-power-page", {content: theContent});
      Webcollage.playPowerPage();
   });
}

Note that the above code sample is an example only.

In this example, Webcollage.$ is used to call the jQuery API which is built into the Power Page. It is used here to delay the call to initPowerPage until the containing div is ready on the page. (If your site facilitates a better mechanism to ensure the availability of that div, you may use it instead.)

  • initPowerPage (container, options)

    The initPowerPage function inserts the Power Page content to the relevant location on the page. If you used a feed and the content is already included on the page, you do not need to call this function. Otherwise, calling this function adds the content to the page.

    The function receives three parameters:

    • container (mandatory): The page location that should include the content. You may either pass a DOM element, a jQuery object, or a jQuery selector (see http://api.jquery.com/category/selectors/ for details). Unless you have set up the content in a unique way, pass ‘#wc-power-page‘.
    • options (optional) – A JavaScript structure containing additional options. The supported options are:
      • autoPlayAndStop. This option is false by default. If true, indicates that the content is automatically activated. If you use this option, there is no need to call the playPowerPage and stopPowerPage functions.

        Note: Do not use this flag if the method your tabbing system uses to show and hide a tab does not conform with the jQuery :visible selector (see: http://api.jquery.com/visible-selector/).

      • resizeCallback. A callback function called when the activation of the content is complete and all dimensions are calculated. The Webcollage system passes two parameters to the function: width and height, which represent the width and height of the Power Page (in pixels). You may use this function to adjust the container’s dimensions so it correctly accommodates the Power Page content.

Other articles in this section:

  1. Installing Shopper Answers
  2. Overview
  3. Overview
  4. Assigning Moderators
  5. Installing Shopper Ratings
  6. Final Deployment
  7. Shopper Ratings Setup
  8. Ratings Moderation
  9. Exporting Data
  10. Advanced Content Integration Guide (current article)