API Analytics v1.0

❗️

This version of Bazaarvoice API Analytics is no longer supported for new integrations. Please refer to BV Pixel for the latest version.

This tutorial covers how to include the required analytics for customers using the Bazaarvoice Conversations API. Developers will learn about the different analytics tags and walk-through the steps involved in including API Analytics in the Bazaarvoice Conversations API implementation.

Overview

API Analytics Tags pass transaction and/or conversion data from a client's web site to Bazaarvoice. Using this data, Bazaarvoice is able to report on the influence that user-generated content (UGC) has on transactions or conversions. While transaction analytics track users interaction, the more specific conversion captures an event where someone browsing the client's site has indicated that they have completed the desired or intended use path, e.g. purchase an item. There are two types of conversions. E-commerce conversion and Non-commercial conversion:

E-commerce

    An event that results in an eCommerce transaction.

Non-commercial

     Conversions don't have to be sales but can be any key performance indicator (KPI) that matters for your               business. Examples include signing up for an e-mail, completing a download, or user registration.

Benefits of analytics

Adding the Bazaarvoice Analytics to your transaction and conversion pages helps ensure overall success of your implementation and provides the best way to measure the value that Bazaarvoice provides to your organization. It also helps us, Bazaarvoice, to measure how well our solution is performing for you, which in turn helps us to make future improvements.

Capturing the relationship between consumer generated content and client's actions is made possible by the API Analytics FeatureUsed tagging. Knowing the impact of or the influence which UGC has on a consumer's experience is mutually beneficial to both clients and Bazaarvoice. These analytics provide an indication or forecast of the likelihood of making a purchase (or conversion), as well as demonstrate the power and benefit of UGC.

The Bazaarvoice Analytics for API correlates shopper activity—such as reading reviews, questions, and answers—to conversion results. From this data, you can gain insights such as:

  • Do shoppers who interact with reviews convert better than users who do not?
  • Is a shopper more inclined to purchase products for which they have read reviews over products for which they have not?
  • In an A/B test, do certain variations of features affect conversion better than others?

Our ROI reporting shows the precise impact our solutions have on your organization and the value you get from deploying Bazaarvoice. Additionally, If the analytics data contains an email address and at least one product ID, Bazaarvoice can send Feed less Post Interaction Email (PIE) automatically to the purchaser.

Requirements

The following list displays some of the provisions that should be addressed prior to API Analytic implementation:

  1. Familiarize yourself with the Terms of Use
  2. Enable the Conversion Impact Report

        Conversations PRR

                 Need to enable first and third party cookies. This request should be made to your Bazaarvoice                  representative

         Conversations

                 Conversion Impact Report is automatically enabled.

  1. Obtain a BV loader file from Bazaarvoice.

        Legacy Conversations (PRR)

                 Open a Support Ticket to request the BV loader file. We plan to move to an automated process in the                  future.

        Conversations with Configuration Hub

                 The BV loader file file will automatically be created when you deploy an Implementation to a Deployment                  Zone in Configuration Hub.

        Conversations PRR

                 Open a Support Ticket to request the scoutfile. We plan to move to an automated process in the                   future.

         Conversations

                  A scoutfile will automatically be created when you deploy an Implementation to a Deployment Zone in                   Configuration Hub.

  1. After confirming the deployment of your BV loader file, load the bazaarvoice javascript file on your page:

    Please note that the 'client_name' is case sensitive
  2. Understand and agree upon transaction nomenclature

📘

Previous analytic solutions required clientId, dc, and environment values. These are no longer needed and are obtained through the loader file.

Analytic tags

The following section details the analytic tags that must be present in a standard Bazaarvoice Conversations API implementation.

Transaction analytics tags

Obviously, clients want to know if a user has read or interacted with user-generated content. Perhaps the content influenced a purchase? Or the consumer generated content aided a user finding the correct fit. Knowing that a potential user requested a page containing user-generated content is one thing, but knowing that they scrolled the user-generated content into view and interacted with it provides an even better insight into a potential user interest.

Questions such as “Was the UGC in view longer than a specified time” and “How did they interact with the content” can be answered by implementing transactional analytic tagging”. These tags are meant to be in-depth and provide a variety of conclusive measurements.

Page view product

When a product detail page is requested and ultimately rendered, the API analytics code trackPageView should be executed. By firing this JavaScript code, data specific to the product page, as well as unique to the end user, is collected. This information is later used as part of the user experience to understand users habits and how they interact with the product details page. This understanding of user interaction with the page (and all the API analytics collected) is imperative in understanding and improving conversion.

An appropriate time to execute the trackPageView code would be with the jQuery document.ready. This will ensure the code executes only once, when the Document Object Model (DOM) is available for JavaScript. A sample of that is seen here:

 $(document).ready(function() {
            BV.pixel.trackPageView({
              bvProduct: 'RatingsAndReviews',
              productId: 'LXS',
              brand: 'Kenmore',
              type: 'Product',
              categoryId: 22,
              rootCategoryId: 'electronics',
              numReviews: 30,
              numQuestions: 12,
              numAnswers: 4,
              avgRating: 4.4,
              percentRecommended: 100
            });
          });

Many of the values for the trackPageView analytics tracking code come from the Conversations API response. There are a variety of API calls to obtain these values. For the purpose of this documentation we will be minimizing the number of requests and use the following:

http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=nagxt74g2vmt9k68c5uzc39d&filter=productid:867117&stats=reviews,questions&Include=products

and using the results to populate the various Value Path fields. However there may be other strategies to obtain this data.

When multiple Bazaarvoice products are used on the same page (e.g. 'ratings and reviews' and 'ask and answer'), the use of the bvProduct parameter is highly recommended. This allows the Conversion Impact Report to be granular to the specific bazaarvoice product. Furthermore, when using the bvProduct it is required that the numQuestions and numAnswers be included.

The type parameter is used to capture the category of the page where the UGC is used. Using the Bazaarvoice API allows UGC to be inserted throughout a website, however the most common locations where UCG is used on 'Product' pages and 'Category' pages.

FieldValue PathPrioritySample value
productId
Required
'867117'
bvProduct
Recommended
'RatingsAndReviews' |'AskAndAnswer' | 'Curations'
brand'Includes.Products."PRODUCT_ID".Brand.Name'
Recommended
'GoPro'
type
Required
'Product' | 'Category' | 'Embedded' | 'Submission' | "Misc'
categoryId'Includes.Products."PRODUCT_ID".CategoryId'
Recommended
'Electronics_Helmet_Cameras'
rootCategoryId
Recommended
'electronics'
numReviews'TotalResults'
Required
if bvProduct = 'RatingsAndReviews'
7
numQuestions'Includes.Products."PRODUCT_ID".QAStatistics.TotalQuestionCount'
Required
if bvProduct = 'AskAndAnswer'
4
numAnswers'Includes.Products."PRODUCT_ID".QAStatistics.TotalAnswerCount'
Required
if bvProduct = 'AskAndAnswer'
4
avgRating'Includes.Products."PRODUCT_ID".ReviewStatistics.AverageOverallRating'
Recommended
3.7143
percentRecommended'Includes.Products."PRODUCT_ID".ReviewStatistics.RecommendedCount'
/'Includes.Products."PRODUCT_ID".ReviewStatistics.TotalReviewCount'
Optional
7/7
Track in view

trackInView should be used to indicate that CGC is merely visible on the page. This tag is triggered when consumer-generated content is made visible in the browser window and will only be triggered once per binding. The events this tag binds to are high-volume events so code internal to the tag will filter (or debounce) events to prevent excessive CPU load. The trackInView analytics is more granular than the PageViewProduct but less specific than the ViewedCGC analytics.

When multiple Bazaarvoice products are used on the same page (e.g. 'ratings and reviews' and 'ask and answer'), the FeatureUsedInView should be called twice. Each call should use the bvProduct parameter and is highly recommended. This allows the Conversion Impact Report to be granular to the specific bazaarvoice product. Furthermore, when using the bvProduct it is required that the numQuestions and numAnswers be included.

FieldValue PathPrioritySample value
productId
Required
'GoPro'
brand
Recommended
'RatingsAndReviews' | 'AskAndAnswer' | 'Curations'
brand'Includes.Products."PRODUCT_ID".Brand.Name'
Recommended
'Electronics_Helmet_Cameras_Helmet_Cams'

The following table is a set of control parameters that are not sent with the tag but control the tag's behavior. The parameters must appear in the data layer.

FieldDefault valuePriorityDescription
containerId
Required
Id of the UGC container (DOM element)
minPixels100
Optional
Minimum number of vertical pixels of the UGC container that must be displayed for UGC to be considered visible.

trackInView is triggered when consumer-generated content is first made visible. A sample of that is seen here:

          var inViewData = {
            productId: 'LXS',
            bvProduct: 'RatingsAndReviews',
            brand: 'Kenmore',
            categoryId: 22,
            rootCategoryId: 'electronics'
          };

          // Triggers an analytics event once 250 pixels of the 'bvUGC' container
          // are in the viewport.
          BV.pixel.trackInView(inViewData, {
            minPixels: 250,
            containerId: 'bvUGC'
          })
Track viewed UGC

trackViewedUGC should be used to indicate that UGC visible on the page and has been in the viewport for an amount of time. This tag will only be triggered once per binding.

FieldValue PathPrioritySample value
productId
Required
'GoPro'
bvProduct
Recommended
'RatingsAndReviews' | 'AskAndAnswer' | 'Curations'
brand'Includes.Products."PRODUCT_ID".Brand.Name'
Recommended
'Electronics_Helmet_Cameras_Helmet_Cams'

The following table is a set of control parameters that are not sent with the tag but control the tag's behavior. The parameters must appear in the data layer.

FieldDefault valuePriorityDescription
containerId
Required
Id of the UGC container (DOM element)
minTime5000
Optional
Minimum amount of time, in milliseconds, that a portion (minPixels) of the element be continuously on screen.
minPixels100
Optional
Minimum number of vertical pixels of the UGC container that must be displayed for UGC to be considered visible.

trackViewedCGC is triggered when consumer-generated content is made visible for a set amount of time. A sample of that is seen here:

          var inViewData = {
            productId: 'LXS',
            bvProduct: 'RatingsAndReviews',
            brand: 'Kenmore',
            categoryId: 22,
            rootCategoryId: 'electronics'
          };

          // Triggers an analytics event once 250 pixels of the 'bvUGC' container
          // is in the browser viewport and has been visible for 2500 ms.
          BV.pixel.trackViewedCGC(inViewData, {
            minPixels: 250,
            minTime: 2500,
            containerId: 'bvUGC'
          })
Feature used

It's not enough to know that a users has viewed a product page, but it is valuable to also know how end users interact with consumer generated content on a web page. This information can provide insights on the information users value before making a conversion, or purchase. Capturing the relationship between consumer generated content and client's actions is made possible by the API Analytics Feature Used tagging. The following is a partial list of users events that indicate user interaction with consumer generated content.

  • Filtering (age ranges filters, gender filters)
  • Sorting (e.g. Top rated, least rated, most recent)
  • Paginating
  • Viewing Image
  • Writing Review
  • Viewing Video
  • Helpfulness Voting

The FeatureUsed analytics js code should execute each time a user interacts with a control that displays or manipulates any UGC. This can include button click events which filter content, a hover event which brings up a modal dialog, or a tablet swipe event which fetches additional UGC.

The example below queues the FeatureUsed event and associated parameters when the user clicks a control with id 'sort_UGC':

          $( "#sort_UGC" ).click(function() {
            BV.pixel.trackEvent('Feature', {
              type: 'Used',
              name: 'Feature_Button',
              brand: 'Test Brand',
              productId: '1234567-bunnyhat',
              bvProduct: 'RatingsAndReviews',
              categoryId: 'hats',
              detail1: 'sort',
              detail2: 'descending'
            });
          }); 
FieldValue PathPrioritySample value
productId
Required
'GoPro'
bvProduct
Recommended
'RatingsAndReviews' | 'AskAndAnswer' | 'Curations'
brand'Includes.Products."PRODUCT_ID".Brand.Name'
Recommended
'Electronics_Helmet_Cameras_Helmet_Cams'
categoryId'Includes.Products."PRODUCT_ID".CategoryId'
Recommended
'electronics'
rootCategoryId
Recommended
name
Required
Name of the feature used (e.g 'paginate'). See transaction nomenclature
detail1
Required
See transaction nomenclature discussion below
detail2
Recommended
See transaction nomenclature discussion below

When multiple Bazaarvoice products are used on the same page (e.g. 'ratings and reviews' and 'ask and answer'), the use of the bvProduct parameter is highly recommended. This allows the Conversion Impact Report to be granular to the specific bazaarvoice product. Furthermore, when using the bvProduct it is required that the numQuestions and numAnswers be included.

Conversion analytics tags

The following three analytic measurements, Non-commerce Conversion, E-commerce Conversion, and PII -Conversion Transaction deal specifically with the concept of conversion. The conversion rate is the percentage of users who take a desired action. The archetypical example of conversion rate is the percentage of website visitors who make a purchase on the site. In the context of a non-ecommerce site "conversion" means a user has taken a desired path or completed an action upon the site. For example, registering with the site or completing a download. Again, the definition of "conversion" depends on the ultimate desired outcome. In order to capture the conversion analytics, it is necessary for only one of the analytic measurements described below to be executed, although it is certainly possible to capture multiple conversions events. The solution choosen should be consistent with your definition of "conversion".

Non-commerce conversion

For non eCommerce sites, the analytics metric that should be implemented is described here. Known as a non-commerce Conversion, this analytic event should fire when an action such as the following takes place:

  • Registering a user
  • Signing up for a subscription (whether paid or free)
  • Downloading trial software, a whitepaper, or something else. This presumably will predispose people to progress in the sales funnel
  • Requesting more information
  • Using a certain feature of an application
  • Anything else that can be unambiguously counted by a computer and that you want users to do

The list below describes what data should be collected in non-commerce conversion.

FieldValue PathPrioritySample value
type
Required
'TestConversion'
label
Recommended
'A conversion testing operation'
value
Required
1
//create the ConversionnData object
          var ConversionData = {
          label: 'A conversion testing operation',
          value: 1,
          type: 'TestConversion'
        };
        BV.pixel.trackConversion(ConversionData); 
E-commerce conversion

Fire an E-Commerce Conversion event once the user has completed a purchase. The logical time to fire this event is when all the necessary information is be available. This will often be after a payment has been processed, or when loading of a payment confirmation page. The following lists the necessary data for execute an E-Commerce Conversion analytics event.

FieldValuePrioritySample value
orderId
Required
'EX-123'
price
Required
Item specific - 50.00
tax
Required
8.25
shipping
Recommended
25.00
total
Required
133.25
sku
Required
Item specific - '1234567-1'
city
Recommended
'Austin'
state
Recommended
'TX'
country
Recommended
'USA'
shippingDate
Optional
Item specific - '2014-12-21'
shippingDelay
Optional
Item specific - '23'
quantity
Required
Item specific - '3'
currency
Required
'USD'
label
Recommended
category
Optional
Item specific - 'electronics'
imageURL
Optional
Item specific - http://www.someserver.com/images/someimage.jpg
name
Required
Item specific - RXV CD player
        //create the TransactionData object
        var TransactionData = {
          orderId: 'EX-123',
          city: 'Exampleville',
          state: 'Texas',
          country: 'USA',
          zip: '78753',
          tax: "8.25",
          shipping: "25.00",
          total: "133.25",
          currency: "USD",
          items: [
            {
              sku: '1234567-1',
              name: 'RXV CD player',
              imageUrl: "http://www.someserver.com/images/someimage.jpg",
              category: "electronics",
              quantity: '1',
              price: "50.00",
              PIEDate: "2014-12-21"
            },
            {
              sku: '1234567-2',
              name: 'HDMI cable 100 ft',
              imageUrl: "http://www.someserver.com/images/someimage.jpg",
              category: "cables",
              quantity: '1',
              price: "10.00"
            }
          ]
        };
        BV.pixel.trackTransaction(TransactionData);

Note The sku is also the ExternalProductID and should match the same value sent to BV in the product feed

Note``ShippingDate & ShippingDelay define the the when to send the Post Interaction Email (PIE). Either value may be defined, but not both. ShippingDate is a specific to send the email while ShippingDelay is days after the purchase date to send an email.

Even though personally identifiable information (e.g. nickname, email, userId) can be contained within the TransactionData object (as shown above), only the fields specific to the tag are sent on for processing. The PIIConversion Transaction on the other hand expects personal data and is more secure in handle it.

E-Commerce conversion with PII

Conversions are treated specially in that they are expected to contain PII data (since they are used by the BV Pixel to power feedless PIE). As such, Conversion events have a allowlist of fields that are not considered to contain PII (see the BV Pixel documentation for details on allowlisted fields).

If the provided data contains a field that is not allowlisted then the field is assumed to contain PII data. This will cause two Conversion events to be transmitted. The first event will be of class PIIConversion and contain all the fields in data. The second event will be of class Conversion and will only contain the allowlisted fields from data.

While the Conversion Transaction is used for reporting, the PII Conversion Transaction is used for feedless post interaction emails and Ask a Product Owner (APO).

FieldValuePrioritySample value
orderId
Required
'EX-123'
email
Required
'[email protected]'
nickname
Recommended
'Mikey124' -used to address specific user in PIE
userId
Required
'TestCustomer-123' - used for sites using client mastered site auth
price
Required
Item specific - 50.00
tax
Required
8.25
shipping
Recommended
25.00
Required
Required
133.25
sku
Required
Item specific - '1234567-1'
city
Recommended
'Austin'
state
Recommended
'TX'
country
Recommended
'USA'
quantity
Required
Item specific - 3
currency
Required
'USD'
label
Recommended
category
Optional
Item specific - 'electronics'
imageURL
Optional
Item specific - http://www.someserver.com/images/someimage.jpg
name
Required
Item specific - RXV CD player
//create the TransactionData object
        var TransactionData = {
          orderId: 'EX-123',
          city: 'Exampleville',
          state: 'Texas',
          country: 'USA',
          zip: '78753',
          userId: 'TestCustomer-123',
          email: '[email protected]',
          nickname: 'Test',
          tax: "8.25",
          shipping: "25.00",
          total: "133.25",
          currency: "USD",
          items: [
          {
            sku: '1234567-1',
            name: 'RXV CD player',
            imageUrl: "http://www.someserver.com/images/someimage.jpg",
            category: "electronics",
            quantity: '1',
            price: "50.00"
          },
          {
            sku: '1234567-2',
            name: 'HDMI cable 100 ft',
            imageUrl: "http://www.someserver.com/images/someimage.jpg",
            category: "cables",
            quantity: '1',
            price: "10.00"
          }
        ]
      };

  BV.pixel.trackTransaction(TransactionData);

Verify data capture

Just as important as implementing the Analytics tags is making sure that the Conversion Impact Report is also gathering the data. To check this, log into Workbench and hover over Reports. Select the Conversion Impact Report option.

When data is being collected, you are able to filter and query reports for different time periods and products. If there is no data being collected, a message is displayed with instruction on how to set up the report.

Note Data captured is not immediately available, the typical time for data to populate into the Conversion Impact Report is 24 hours.

Appendix

Sample HTML pages

The sample API Analytics page exists to demonstrate how API tags should be incorporated within a website. The sample is only a discussion point on how API tags should be implemented. Included in the sample is a hard-coded Products Details page with UGC and a sample confirmation page emulating an e-commence transaction.

Additional information and source code for the sample is available in this GitHub repo.

Transactions events nomenclature

In order to capture the impact of different user events on UGC data (e.g. sorting, filtering, paginating), Featured Used transaction analytic tags are used. To differentiate between the UGC interaction events, a naming standard should be used. The name, detail1, and detail2 parameter used in the Featured Used transaction analytic tags should be set up accordingly.

  1. Name - the name value should be a unique value
  2. Detail1 - this value should be the action that is occuring. Bazaarvoice suggest the following terms: sort, filter, paginate
  3. Detail2 - if applicable, a secondary description of the event (e.g. ascending, descending)

The name and detail1 field should identify the type of control that the user is interacting with, e.g. filter, pagination, sort. Bazaarvoice has identified the following preferred terms; filter, sort, paginate, swipe. The combination of the name, detail1 and detail2 field should uniquely identify the control on the page. The metrics automatically aggregate by feature name, detail1 and detail2 (in that order). This allows you to extract hierarchical metrics when using carefully crafted detail attributes.

Support

Contact our Support team who will be able to tell you in which platform your client instance is installed.