Passive/Macro-level analytic events

Clients want to know if a user has read or interacted with user-generated content. Perhaps the content influenced a purchase or aided a customer finding the correct fit. Knowing that a user requested a page containing user-generated content is one thing, but knowing that they scrolled to 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 analytic tagging. These tags are meant to be in-depth and provide a variety of conclusive measurements.

trackPageView()

BV.pixel.trackPageView(pageViewData)

This method communicates data specific to the product page. This information is used later to evaluate a user's habits such as how they interact with your product details page. This understanding of user interaction with the page is imperative to understanding and improving conversion.

Arguments

Name	Type	Default	Description	Priority
`pageViewData`	Object	N/A	An object containing data related to the Bazaarvoice products implemented on the page	Required

Usage

Execute trackPageView() when a product detail page is fully rendered and the page view data (see below) is available. A simplified example of that is seen in the following example. Note that the trackPageView() method is used immediately before the end body tag after all content has loaded:

<html>
<head>...</head>
<body>
<!-- Your content here -->
<script>
   BV.pixel.trackPageView(pageViewData);
</script>
</body>
</html>

A similar effect can be achieved using jQuery's ready() method.

Page View data

The Page View data is passed to trackPageView(pageViewData) as an object as demonstrated in the following example:

var pageViewData = {  
    bvProduct: 'RatingsAndReviews',  
    productId: 'LXS',  
    brand: 'brandname',  
    type: 'Product',  
    categoryId: 'Electronics_washing',  
    rootCategoryId: 'electronics',  
    numReviews: 30,  
    avgRating: 4.4,  
    percentRecommended: 100  
  }  
  BV.pixel.trackPageView(pageViewData);

When multiple Bazaarvoice products are used on the same page (such as Ratings and Reviews, Ask and Answer), you should execute trackPageView() once for each Bazaarvoice product, including the appropriate value for bvProduct along with the other data. This allows the Conversion Impact report (CIR) to be granular to the specific Bazaarvoice product.

var defaultPageViewData = {  
    productId: 'LXS',  
    brand: 'brandname',  
    type: 'Product',  
    categoryId: 'washingmachine',  
    rootCategoryId: 'electronics'  
  }

  var rrPageViewData = clone(pageViewData, {  
    bvProduct: 'RatingsAndReviews',  
    numReviews: 30,  
    avgRating: 4.4,  
    percentRecommended: 100  
  })  
  BV.pixel.trackPageView(rrPageViewData);

  var aaPageViewData = clone(defaultPageViewData, {  
    bvProduct: 'AskAndAnswer',  
    numQuestions: 12,  
    numAnswers: 4  
  }  
  BV.pixel.trackPageView(aaPageViewData);

In the pseudo code above clone() represents a function that creates a new object by combining the properties of its arguments.

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 is on 'Product' pages and 'Category' pages.

Field	Type	Sample Value	Priority
bvProduct	String	'RatingsAndReviews' \| 'AskAndAnswer'	Required
productId	String	'LXS-13234'	Required
brand	String	'GoPro'	Recommended
type	String	'Product' \| 'Category' \| 'Embedded' \| 'Submission' \| 'Misc'	Required
categoryId	String	'Electronics_Helmet_Cameras'	Recommended
rootCategoryId	String	'electronics'	Recommended
numReviews	Number	7	Required if bvProduct = 'RatingsAndReviews'
numQuestions	Number	5	Required if bvProduct = 'AskAndAnswer'
numAnswers	Number	4	Required if bvProduct = 'AskAndAnswer'
avgRating	Number	3.7143	Recommended
percentRecommended	Number	.70	Optional

How to find Page View data

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 use the following request, which contains all the necessary data:

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

The table below identifies the JSON path to each value needed by trackPageView().

Field	Value Path
productId	N/A - In the API request
bvProduct	Use one of 'RatingsAndReviews' \| 'AskAndAnswer' as appropriate
brand	Includes.Products.PRODUCT_ID.Brand.Name
type	Use one of 'Product' \| 'Category' \| 'Embedded' \| 'Submission' \| "Misc'
categoryId	Includes.Products.PRODUCT_ID.CategoryId
rootCategoryId	N/A
numReviews	TotalResults
numQuestions	Includes.Products.PRODUCT_ID.QAStatistics.TotalQuestionCount
numAnswers	Includes.Products.PRODUCT_ID.QAStatistics.TotalAnswerCount
avgRating	Includes.Products.PRODUCT_ID.ReviewStatistics.AverageOverallRating
percentRecommended	Includes.Products.PRODUCT_ID.ReviewStatistics.RecommendedCount
	Includes.Products.PRODUCT_ID.ReviewStatistics.TotalReviewCount

trackImpression()

BV.pixel.trackImpression({  
  contentId: '93405153',  
  productId: 'LXS',  
  categoryId: '824213434',  
  contentType: 'review',  
  bvProduct: 'RatingsAndReviews',  
  brand: 'brandname'  
});

This method communicates the various pieces of user-generated content on a given page back to Bazaarvoice. For each review, question or answer on a page, a trackImpression method must be executed.

Arguments

Name	Type	Default	Description	Priority
`contentId`	String	N/A	Id of the UGC content	Required
`productId`	String	N/A	Id of the product	Required
`bvProduct`	String	N/A	Name of the Bazaarvoice product using specific UGC ('RatingsAndReviews' \| 'AskAndAnswer' \| 'Curations')	Required
`contentType`	String	N/A	Type of content(review\|question\|answer)	Recommended
`categoryId`	String	N/A		Recommended
`brand`	String	N/A	Brand name of what the content (review, question, etc) is about.	Recommended

Usage

trackImpression indicates specific user-generated content (UGC) is on the page. This is not considered an interaction since this tag is triggered on the page load. It is most likely that users have not yet had the opportunity to interact with it. trackImpression will trigger once for each piece of UGC content. This method triggers regardless of whether the content is in view or not.

<html>
<head>...</head>
<body>
<!-- Your content here -->
<script>
BV.pixel.trackImpression({
  contentId: '93405153',
  productId: 'LXS',
  categoryId: '824213434',
  contentType: 'review',
  bvProduct: 'RatingsAndReviews',
  brand: 'brandname'
});
</script>
</body>
</html>

A similar effect can be achieved using jQuery's ready() method.

How to find Track Impression data

Most of the values for the trackImpression() analytics tracking code are associated with the product. However, the contentId, which identifies the specific piece of UGC, is available from the API call. For the purpose of this documentation, we will use the following request, which contains all the necessary data:

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

The table below identifies the JSON path to each value needed by trackImpression().

Field	Value Path
contentId	`'Results.Id'`
productId	N/A - In the API request
bvProduct	Use one of 'RatingsAndReviews' \| 'AskAndAnswer' \| 'Curations' as appropriate
categoryId	`'Includes.Products."PRODUCT_ID".CategoryId'`
brand	`Includes.Products."PRODUCT_ID".Brand.Name`

trackInView()

BV.pixel.trackInView(inViewData, {  
  minPixels: 250,  
  containerId: 'bvUGC'  
})

trackInView should be used to indicate that UGC is visible on the page. This tag is triggered when user-generated content is made visible in the browser window and will only be triggered once per binding.

Arguments

Name	Type	Default	Description	Priority
`inViewData`	Object	N/A	An object containing data related to the Bazaarvoice products implemented on the page	Required
`minPixels`	Number	100	Minimum number of pixels the UGC container must be view for the analytics event to execute	Optional
`containerId`	String	N/A	ID of the HTML element containing the user-generated content (UGC)	Required

Usage

trackInView() is triggered when user-generated content is first made visible in the browsers viewport. No additional work is needed to trigger this event when the indicated container becomes visable.

<html>
  <head>...</head>
  <body>
  <!-- Your content here -->
  <script>
  BV.pixel.trackInView(inViewData, {
    minPixels: 250,
    containerId: 'bvUGC'
  })
  </script>
  </body>
  </html>

The events to which this tag binds 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 trackPageView() but less specific than the trackViewedUGC analytics.

When multiple Bazaarvoice products are used on the same page (such as Ratings and Reviews and Ask and Answer), trackInView() 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.

TrackInView data object

The inViewData is passed to trackInView(inViewData, ...) as an object as demonstrated in the following example:

var inViewData = {  
  productId: 'LXS',  
  bvProduct: 'RatingsAndReviews',  
  brand: 'brandname'  
};

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

The following table shows the expected parameters and values expected in the inViewData object.

Field	Type	Sample Value	Priority
productId	String	'LXS-13234'	Required
bvProduct	String	'RatingsAndReviews' \| 'AskAndAnswer'	Required
brand	String	'brandname'	Recommended

How to find In View Data

Many of the needed values for the inViewData() 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 use the following request, which contains all the necessary data:

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

The table below identifies the JSON path to each value needed by inViewData().

Field	Value Path
productId	N/A - in the API request
bvProduct	Use one of 'RatingsAndReviews' \| 'AskAndAnswer' as appropriate
brand	`Includes.Products."PRODUCT_ID".Brand.Name`

trackViewedUGC()

// 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.trackViewedUGC(inViewData, {  
  minPixels: 250,  
  minTime: 2500,  
  containerId: 'bvUGC'  
})

trackViewedUGC is triggered when user-generated content is made visible for a set amount of time. A sample of that is seen above.

Arguments

Name	Type	Default	Description	Priority
`inViewData`	Object	N/A	An object containing data related to the Bazaarvoice products implemented on the page	Required
`minPixels`	Number	100	Minimum number of pixels the UGC container must be view for the analytics event to execute	Optional
`minTime`	Number	5000	Minimum amount of time, in milliseconds, that a portion (minPixels) of the element be continuously on screen	Optional
`containerId`	String	N/A	ID of the HTML element containing the user-generated content (UGC)	Required

Usage

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

ViewedUGC data object

As seen in the previous examples the data object should contain three values:

Field	Type	Sample Value	Priority
productId	String		Required
bvProduct	String	'RatingsAndReviews' \| 'AskAndAnswer'	Required
brand	String	'brandname'	Recommended

Field descriptions

Field	Description
bvProduct	This is the value of the the Bazaarvoice offering. 'RatingsAndReviews' is used when viewing content providing user's sentiment. 'AskAndAnswer' should be used when UGC is used with questions and answers.
brand	The brand name of the product.
type	The type of page that is being viewed. Typically this will be "Product", but may also be 'Category" or 'Submission' if those are classes of pages containin the UGC.
categoryId	This value should be obtained from the product feed.
rootCategoryId	This value should be obtained from the product feed.