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

The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

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 consumer generated content (CGC) 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 CGC has on a consumer's experience is mutually beneficial to both clients and Bazaarvoice. These analytics provide an indication or forecast of the likelyhood of making a purchase (or conversion), as well as demonstrate the power and benefit of CGC.

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 Feedless 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 - See How to determine your platform in the Appendix if you do not already know on which platform you client instance is installed.
    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.
  3. 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.
  4. 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

  5. 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 consumer generated content. Perhaps the content influenced a purchase? Or the consumer generated content aided a customer finding the correct fit. Knowing that a potential consumer requested a page containing consumer generated content is one thing, but knowing that they scrolled the consumer generated content into view and interacted with it provides an even better insight into a potential customer interest.

Questions such as “Was the CGC 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.

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.

Field Value Path Priority Sample 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' 5
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

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

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 immediatley 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 CGC 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 CGC data (e.g. sorting, filtering, paginating), Featured Used transaction analytic tags are used. To differentiate between the CGC 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.

How to determine your platform

All API key as associated with a platform. Two methods are available to determine this information. Click to read more.

Support

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