API Analytics v1.0

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.

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.

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.

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'
          })
        

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

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.

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'
          })
        

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

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

          $( "#sort_CGC" ).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'
            });
          });
        

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.

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.

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

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.

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

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 whitelist of fields that are not considered to contain PII (see the BV Pixel documentation for details on whitelisted fields). If the provided data contains a field that is not whitelisted 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 whitelisted 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).

//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);