---
updatedAt: 2026-03-30T09:13:41.000Z
agentTools:
projectIndex: https://developers.bazaarvoice.com/v1.0-ConversationsAPI/llms.txt
---
# API Analytics v1.0
> ❗️ This version of Bazaarvoice API Analytics is no longer supported for new integrations. Please refer to [BV Pixel](/v1.0-ConversationsAPI/docs/bv-pixel-overview) 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](#transaction-analytics-tags) and/or [conversion](#conversion-analytics-tags) 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](#transaction-analytics-tags) or [conversions](#conversion-analytics-tags). While [transaction](#transaction-analytics-tags) 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](#conversion-analytics-tags). 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](https://www.bazaarvoice.com/legal/terms-of-use/conversations-api/)
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.
3. Obtain a BV loader file from Bazaarvoice.
**Legacy Conversations (PRR)**
Open a [Support Ticket](https://developers.bazaarvoice.com/page/support) 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](https://developers.bazaarvoice.com/page/support) 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](/v1.0-ConversationsAPI/docs/conversations-api-analytics#transactions-events-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:
```javascript
$(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
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' | 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.
| Field | Value Path | Priority | Sample 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.
| Field | Default value | Priority | Description |
| ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| containerId | | Required
| Id of the UGC container (DOM element) |
| minPixels | 100 | 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:
```javascript
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.
| Field | Value Path | Priority | Sample 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.
| Field | Default value | Priority | Description |
| ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| containerId | | Required
| Id of the UGC container (DOM element) |
| minTime | 5000 | Optional
| Minimum amount of time, in milliseconds, that a portion (minPixels) of the element be continuously on screen. |
| minPixels | 100 | 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'
});
});
```
| Field | Value Path | Priority | Sample 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](#transaction-nomenclature) |
| detail1 | | Required
| See [transaction nomenclature](#transaction-nomenclature) discussion below |
| detail2 | | Recommended
| See [transaction nomenclature](#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.
| Field | Value Path | Priority | Sample 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.
| Field | Value | Priority | Sample 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 - |
| 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).
| Field | Value | Priority | Sample value |
| -------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| orderId | | Required
| 'EX-123' |
| email | | Required
| '' |
| nickname | | Recommended
| 'Mikey124' -used to address specific user in PIE |
| userId | | Required
| 'TestCustomer-123' - used for sites using [client mastered site auth](/v1.0-ConversationsAPI/docs/client-mastered) |
| 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 - |
| 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: 'test.customer@bazaarvoice.com',
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 **Bazaarvoice Portal > Analytics > Ratings & Reviews > Conversions**
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](http://api-analytics-kit.bazaarvoice.com/) page exists to demonstrate how API tags should be incorporated within a website. The [sample](http://api-analytics-kit.bazaarvoice.com/) is only a discussion point on how API tags should be implemented. Included in the [sample](http://api-analytics-kit.bazaarvoice.com/) 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](https://github.com/bazaarvoice/api-analytics/).
# Transactions events nomenclature
In order to capture the impact of different user events on UGC data (e.g. sorting, filtering, paginating), [Featured Used](#collapseFour) 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](#collapseFour) 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](https://developers.bazaarvoice.com/page/support) our Support team who will be able to tell you in which platform your client instance is installed.