treyperry / api-analytics

API Analytics

Bazaarvoice API Analytics starter kit

The Bazaarvoice API Analytics starter kit is a sample consisting of static HTML, CSS, and js that demonstrates how API users should implement the required analytics tags when using the Bazaarvoice API.

Before Downloading:

1. Implementing the API Analytics Tags is required according to the API terms and conditions
2. Read the API Analytics tutorial documentation. Developers should also be familiar with the API Terms of Use.
3. Install the Bazaarvoice Analytics Inspector for Chrome.
4. The code in this GitHub repo is also hosted on a web server. Both the product description page and the conversion page can be considered working samples of the API Analytics starter kit. Users should interact with the pages with the Bazaarvoice Analytics Inspector for Chrome enabled to help understand the implementation.
5. Realize that the starter kit is meant as a sample. It is static, and by no means optimized for speed and scale. There are no calls made to the Conversations API to get product data. The key/value are hard coded in the js file. The code is provided as a means to help API users better understand API analytics.

What is the sample doing?

This tutorial captures a user's actions on the product details page. Accompanying the code on the product details page, is code associated with the conversion event. Bazaarvoice supports various definitions of conversion, both non-commercial conversion and traditional e-commerce conversion. By connecting the user's behavior on the product details page to the conversion page, we are able to track the site conversion rate of those who have interacted with user generated content.

All this is accomplished by adding code that captures how user's interact with the consumer generated content. User events (e.g. viewing the page, scrolling the page, and interacting with the different web inputs) should all be captured within the site. Attaching client-side javascript code to these different events is the responsibility of the site developer.

After the custom code capturing the different parameters is completed and associated with HTML event, the final step is a simple call using the Bazaarvoice API Tracker library.

The tracking code requires 2 arguments:

• the tag name
• an object containing the key/value pairs.

The following samples demonstrate some of the analytic calls:

    _bvapiq.push(['FeatureUsedInView', item]);
    _bvapiq.push(['FeatureUsed', {
        clientID: featureObject.clientID,
        environment: featureObject.environment,
        dc: featureObject.dc,
        name: name,
        brand: featureObject.brand,
        productId: featureObject.productId,
        bvProduct: null,
        categoryId: featureObject.categoryId,
        detail1: detail1,
        detail2: detail2
    }]);

    _bvapiq.push(['ConversionTransaction', TransactionData]);
    _bvapiq.push(['PIIConversionTransaction', TransactionData]);

The bvAnalyticsAPITracker.min.js.gz file send the analytics data to Bazaarvoice servers after collecting from the product details page and the user defined 'conversion' page.

Sample Product Details Page

The javascript on the sample product description page listens for different events. The API Analytics code executes when they occur. The required analytics tags are required for each Bazaarvoice API instance.

Page View Product

Each time a product details page is rendered, the transaction analytics tag 'page view product' is executed. In this sample, the 'page view product' is associated with the page load event. When page load is complete, the analytics code is called and passes an object. The object's key/values pairs are hard coded and are not obtained from a Conversations API call.

---

Feature Used in View

Not all Product Details Pages have Consumer Generated Content (CGC) within the browser's viewable area when the page is rendered. Often, users must scroll to view the CGC. As part of the API Analytics requirements, when the CGC comes in view, must also be captured. This is done by calling the transactional analytics tag 'feature used in view'. This object's key/value pairs differs slightly from the previous 'page view product' by:

1. having additional keys that identify the CGC container Id
2. allow to specify the minimum pixel height that must be viewed before executing
3. specifying a time (milliseconds) the CGC container must be viewed before executing

---

Feature Used

Event handlers are also attached to the various CGC inputs. This aims to capture how users interact with the Conversations data. In order to complete this

Included in the sample are:

1. Clicking "Show/Hide Filter"
2. Selecting an Age or Gender sub-filter
3. Clicking "Write a Review"
4. Interacting with the "Sort"
5. Expanding/contracting the "Read more/less"
6. Voting if the review was helpful
7. Reporting the review
8. Clicking the pagination
9. Clicking the "See All" button
10. Clicking the "Staff" button

---

Conversion Page

The conversion page simulates a page a user would reach upon completing a purchase. With conversion complete, the conversion analytic tags are executed. Both the 'ConversionTransaction' and the 'PIIConversionTransaction' are called in this sample. At a minimim one of the three conversion tags must be included in each Bazaarvoice API instance.

ConversionTransaction

PIIConversionTransaction

Non Transactional Conversion

Hosted Sample:

In addition to providing the starter kit for download, the tutorial is hosted for client interaction.

First, download and install the Bazaarvoice Analytics Inspector for Chrome. Once install you will see the Analytics Inspector icon in the Chrome browser.

Next, visit the product description page hosted API Analytics solutions. Open the Bazaarvoice Analytics Inspector and interact with the page. The tool documents each time an analytics event is captured and sent to Bazaarvoice. Notice the red counter on the icon.

Scroll and click different HTML inputs. Notice Feature events being populated. Event handlers are attached to several HTML inputs which in-turn queue the analytics code.

Also available within the hosted site is a sample conversion page. Again open the page in a browser with the Bazaarvoice Analytics Inspector open. The analytics on this page are executed on page load. There are several options available for defining and capturing conversion events. Conversion is described in detail in the conversion analytics tags section.

Console logs are displayed because within the hosted API Analytics solutions the 'environment' variable is set to 'staging'. This flag is used in the js code to enable console.logs. When the 'environment' flag is set to anything else (including the other accepted value 'production') logging will not occur.

Things to Note

This sample does not make API calls to retrieve and bind client data. Values that should be obtained from the API are hard coded in the HTML and js files. Comments have been added where the values should be obtained from the API.

The sample works in conjunction with the Bazaarvoice Analytics Inspector to aid clients in making sure the implementation is complete.

It is required that a Bazaarvoice team member verify the completion of each implementation.