Note: If you've migrated to BV Pixel v2 (using the BV loader file, bv.js), refer to the BV Pixel v2 documentation. Bazaarvoice encourages you to migrate to BV Pixel v2 for performance improvements and future innovations.

BV Pixel v1, formerly known as the ROI beacon, is a piece of JavaScript code implemented on your conversion pages.

Implementing BV Pixel v1 (bvapi.js)

The BV Pixel is used by a number of Bazaarvoice features. However, it’s primarily needed for running Bazaarvoice analytics and for sending interaction data automatically.

BV Pixel can also be used to run A/B tests to evaluate best practices on your site, live, for a sample set of customers, before you implement them for all customers.

The BV Pixel tells Bazaarvoice when a customer converts on your site. There are two types of BV Pixel tags:

  • Generic (non-transactional) conversion tags capture events such as newsletter signups, product registration, downloads of a PDF, and requests for more information about a product or service. You can generate ROI reports related to key performance indicators.
  • Transaction (transactional) conversion tags capture purchase data when a customer buys a product. For example, the data captured might include SKUs, email addresses, and postal addresses. These customer transaction details are required to send interaction data automatically. You can also use this data to generate ROI reports tied to revenue.

After you implement the BV Pixel on your site, you can generate a number of different dashboard reports that show how users interact on your site, and to understand the value of your implementation.

Note: You must install the BV Pixel before you can use Bazaarvoice reports, review requests (formerly post-interaction email or PIE), and run A/B tests on your website.

Implementing the BV Pixel on your transaction and conversion pages

  1. Add the BV Pixel bvapi.js tag to your transaction and conversion pages.
    • Transactional conversion pages refer mainly to product order pages where a purchase transaction event takes place
    • Non-transactional conversion pages refer to review submission, newsletter signups, and store locator pages
  2. You must also add a small snippet of Javascript to these pages, which sends data to Bazaarvoice via SSL (encrypted for security).
Note: If your implementation uses an API, you should implement the BV Pixel with the rest of our analytics tags. To do this, follow the instructions at implementing the BV Pixel with analytics tags.

Add the bvapi.js JavaScript tag

To enable the BV Pixel v1, add a JavaScript tag, the bvapi.js file, to your transaction confirmation pages. The file enables the Bazaarvoice API for your implementation. Include the file on every page where you intend to implement the BV Pixel.

Note: You must implement the BV Pixel on a domain which is on the allowlist (sometimes called a "whitelist"). Bazaarvoice manages the domain allowlist internally. Any changes to the allowlist must be communicated to Bazaarvoice. If you are in the implementation stage of a project, contact your implementation team to request changes. If you are in the support stage, contact Bazaarvoice Support to request changes.

To include the bvapi.js file, you must use your client name, appropriate environment, and locale. The file loads the necessary JavaScript to support tagging. After bvapi.js loads, the tagging code can be placed anywhere after it in the code.

Note: The code in this section uses /bvstaging, which indicates that requests will be routed to the Bazaarvoice staging environment. Do not attempt to use /bvstaging in the production environment.

The following example shows code for the BV Pixel:

<!-- load bvapi.js -->
<script type="text/javascript" 
   src="https://display.ugc.bazaarvoice.com/bvstaging/static/client_name/locale/bvapi.js">
</script>

<!-- tagging code -->
<script type="text/javascript">
   $BV.SI.trackTransactionPageView({
        /* Interaction data goes here...
           See "Adding Integration Tagging" topic for details...
        */
   });
</script>

Replace client_name with the client name value provided by Bazaarvoice using lowercase letters, and replace locale with your locale code. Remove /bvstaging from the URL before launching in your production environment.

Add BV Pixel v1 transaction tagging

Interaction tagging captures detailed information about a user’s interactions enabling ROI measurement. There are two types of interaction tags used:

  • transaction tags
  • conversion tags

This topic covers transaction tagging. The following code example is the JavaScript transaction tag used for ROI measurement. It’s generally placed on your order confirmation page (e.g., payment confirmation, transaction confirmation, thank-you page):

Important:

  • Boldface properties are specific to ROI measurement. All others are used for sending interaction data automatically.

  • Letter case is important.
  • This code is a sample and should not be used as is. You must add/remove properties and associated values as necessary for your specific application requirements.
  • Refer to review request interaction parameters for detailed descriptions of each property.
  • The conversion tagging method only applies to ROI measurement and cannot be used for sending interaction data automatically.
  • SKU must match the product’s ExternalId in your product catalog. Do not default this to standard SKU unless that is the number that is sent in your product catalog.
{code:javascript}
$BV.SI.trackTransactionPageView({
  "orderId" : "55555",
  "tax" : "1.44",
  "shipping" : "10.00",
  "total" : "40.84",
  "city" : "Austin",
  "state" : "TX",
  "country" : "USA",
  "currency" : "USD",
  "items" : [
      {
              "sku" : "2245",
              "name" : "product name",
              "category" : "category name",
              "price" : "13.42",
              "quantity" : "1",
              "imageURL" : "http://test.com/1.jpg"
      },
      {
              "sku" : "2246",
              "name" : "product name2",
              "imageURL" : "http://test.com/2.jpg"
      }
  ],
  "email" : "john@example.com",
  "deploymentZone" : "secondary",
  "locale" : "en_US"
});
{code}   

Transaction parameters

Refer to the following tables for details about parameters for the BV Pixel v1, which are required or recommended. If a recommended parameter is not available on the page, it should not be included at all. For example, if there is no data for the "tax" parameter, do NOT set it to "tax" : "" (an empty string). Instead, remove the parameter completely.

Note: If currency is not included, the currency listed in the Conversion Impact Report will default to USD.
Note: BV Pixel can also be used to enable interaction data automatically. If you set up the BV Pixel to power review request email messages, you'll need to include additional interaction parameters.
Important: All parameters are case sensitive and must be formatted correctly, as shown in the following example:
correct: orderId
incorrect: orderid  order_Id  orderID  OrderId
ParameterRequiredDescriptionExample
citynoThe customer's city."Austin"
countrynoThe customer's country."USA"
currencyyesThe ISO 4217 alphabetic currency code of the order."USD"
emailnoRecommended. The customer's email address. Used to deliver review request email messages.A valid email address, formatted correctly
itemsyes, unless sending non-transactional review requestsRequired for transactional review requests. An array of the individual items in the interaction, such as "order, purchase, transaction".See the item parameters table.
localeno

Optional. Determines the language-specific email template to use.

Required. If you are sending unique templates for multiple locales, you must include this parameter.

"en_US", "en_CA", ru_RU", "en_GB", etc. Example: A Canadian client sending English and French review requests must include either "en_CA" or "fr_CA" depending on the locale of the user.
deploymentZoneyes, if multiple deployment zones are usedThe ID of the deployment zone to which the implementation is deployed. This instructs Bazaarvoice to use the implementation's email templates when sending review request email messages, instead of using Main Site's. The implementation where the templates are configured must be published to the deployment zone before you reference the deployment zone in the interaction feed. If you omit this parameter, main_site is used."secondary_site"
nicknameno, unless nickname slaving is enabledRecommended. The customer's first name or nickname, captured when the customer creates an account. Used to personalize the email greeting."Mary" or "mary75"
orderIdyesThe unique ID of the order."55555"
shippingnoThe cost of shipping the order."10.00"
shippingDate

no

 

Optional. Used instead of the transaction date to determine when Bazaarvoice sends the review requests.Must be in the following format: YYYY-MM-dd (e.g., 2014-12-21)
shippingDelayno

Optional. Used to increase the time (in days) between the transaction date and the date Bazaarvoice sends the review request. This can be useful if you expect delayed fulfillment.

Note: You can use either shippingDate or shippingDelay, but should not use both.
"25"
statenoThe customer's state."TX"
taxnoThe amount of tax applied to the order."1.44"
totalyesThe total amount of the order."40.84"
userIdno, unless using site authentication

Recommended.userId must match the userToken (user id), which is passed to Bazaarvoice during the review submission process. Can be omitted if an ID is not created, as with guest purchasers.

Note: Ensure your review request configuration worksheet reflects this accurately.
"7448dc2"

Items parameters

ParameterRequiredDescriptionExample
categoryno

Recommended. Product category.

Important: Should match the value you provide to Bazaarvoice in the product catalog.
"Shirts"
imageURLno

Highly recommended. Link to the product image. If omitted, we will retrieve the value from our database by matching the sku parameter to the product ExternalId sent in your product catalog.

Important: The URL specified for the imageURL parameter must be a full, absolute URL and not a relative path.
"http://www.test.com/1.jpg"
nameno

Recommended. Product name.

Required if product ExternalId does NOT exist in our database. Otherwise, item is excluded from email.

Important: Should match the value you provide to Bazaarvoice in the product catalog.
"Black t-shirt"
priceyes

Product price used to sort products in the review request by price.

Important: Must include only two (2) decimal places and no currency symbol.
"13.42"
quantityyesPurchase quantity."4"
shippingDate

no

 

Optional Used instead of the transaction date to determine when Bazaarvoice sends the review request.Must be in the following format: YYYY-MM-dd (e.g., 2014-12-21)
shippingDelayno

Optional. Used to increase the time (in days) between the transaction date and the date Bazaarvoice sends the review request. This can be useful if you expect delayed fulfillment.

Note: You can use either shippingDate or shippingDelay, but should not use both.
"25"
skuyes

This is the Bazaarvoice product external ID. Sometimes this is a SKU code, but often it is some other product ID. It is used specifically with Bazaarvoice to uniquely identify your products.

Important: It MUST match the product ExternalId that is sent to Bazaarvoice in your product catalog. If the ID you set for the sku parameter is not in your product catalog, the product will NOT be included in the review request.
"2245"

Add BV Pixel v1 for conversion (non-transactional) tagging

Conversion events accept three high-level parameters to help describe the type of conversion taking place. The following example shows a conversion event in which a user used a “store locator” feature by supplying a zip code value.

For conversion (non-transaction) pages, supply the following data using the sample format.

{code:javascript}
$BV.SI.trackConversion({
    "type" : "StoreLocator",
    "label" : "ProductPage",
    "value" : 78701
});
{code}

Conversion parameters for the BV Pixel v1

ParameterRequiredDescriptionExample
typeyesType of conversion that is taking place. You define the values of this parameter."StoreLocator" or "Download"
labelnoDescriptive label to apply to the conversion."ProductPage" or "ProductSpecification-1234.pdf"
valuenoValue attributed to the conversion."78701" or "1"
Note: Custom non-commerce conversion events can be configured using the type parameter. The amount and type of events are configurable and can be used to create conversion “funnels” that are measured in the Conversion Impact Report. These live configurations will begin to populate in the Conversion Impact Report, under Non-Commerce Goals, after two to three days. After that, no additional configuration is necessary.

PII data

Just like transactions, conversions may contain personally identifiable information (PII). Any parameters supplied to $BV.SI.trackConversion() that are not listed in conversion parameters are assumed to be PII. Refer to Personally identifiable information (PII) for more information.

Note: Non-commerce conversions currently do not trigger interaction data automatically.

Personally identifiable information (PII)

The following parameters for the BV Pixel v1 code are considered to be personally identifiable information (PII) data. PII enables you to send a personalized follow-up email asking the customer to return to your site and contribute content. This message, called a review request email message, helps increase content volume on your site.

Note: Non-commerce conversions currently do not trigger interaction data automatically.
Parameter Required Description Example
nickname no, unless nickname slaving is enabled Recommended.The customer's first name or nickname, captured when the customer creates an account. Used to personalize the email greeting. "Mary" or "mary75"
email no, unless tagging to enable interaction data automatically The customer's email address. A valid email address, formatted correctly
phonenumber no The customer's phone number. A valid phone number, formatted correctly (E164 ).
userId no, unless using site authentication

Recommended. userId must match the userToken (user ID), which is passed to Bazaarvoice during the review submission process. Can be omitted if an ID is not created, such as in the case of guest purchasers.

Note: Ensure your review request configuration worksheet reflects this accurately.
"7448dc2"

PII data

In certain cases, you may want to provide personally identifiable information (PII) as part of a transaction. This includes data such as:

  • email address
  • first name, last name
  • username
  • Facebook ID
  • telephone number
  • physical address, zip code

This data can be provided alongside the transaction data. Any parameters supplied to $BV.SI.trackTransactionPageView() that are not listed in the transaction parameters are assumed to be PII.

Important: Personally identifiable information (PII) information:
  • is never associated with the Bazaarvoice persistent cookie.
  • is always transmitted over HTTPS.
  • is encrypted before writing to disk.
  • is never processed by Bazaarvoice analytics.

Conversion parameters

Parameter Required Description Example
type yes The type of conversion. You define the values of this parameter. "StoreLocator" or "Download"
label no A descriptive label to apply to the conversion "ProductPage" or "ProductSpecification-1234.pdf"
value yes A value to attribute to the conversion "78701" or "1"

PII data

Just like transactions, conversions may contain personally identifiable information (PII) data. Any parameters supplied to $BV.SI.trackConversion() that are not listed in conversion parameters are assumed to be PII.

Review request interaction parameters

Use the following interaction parameters when you are configuring interaction data automatically and BV Pixel v1, as part of the interaction tagging process. If a recommended parameter is not available on the page (such as userId for guest purchasers), it should not be included. For example, if no data is available for the tax parameter, do not set it to "tax" : "" (an empty string). Instead, remove the parameter completely. Item parameters take precedence over global parameters.

Note: All parameters are case sensitive and must be formatted correctly. For example, "userId" should not be "UserID".
Parameter Required Description Example
city no The customer's city. "Austin"
country no The customer's country. "USA"
currency yes The ISO 4217 alphabetic currency code of the order. "USD"
email no Recommended. The customer's email address. Used to deliver the review requests. A valid email address, formatted correctly
phonenumber no Recommended. The customer's phone number. Used to deliver the review requests. A valid phone number, formatted correctly (E164 )
items yes, unless sending non-transactional review requests Required for transactional review requests. An array of the individual items in the interaction, such as "order, purchase, transaction". See the item parameters table.
locale no

Optional. Determines the language-specific email template to use.

Required. If you are sending unique templates for multiple locales, you must include this parameter.

"en_US", "en_CA", ru_RU", "en_GB", etc. Example: A Canadian client sending English and French review requests must include either "en_CA" or "fr_CA" depending on the locale of the user.
deploymentZone yes, if multiple deployment zones are used The ID of the deployment zone to which the implementation is deployed. This instructs Bazaarvoice to use the implementation's email templates when sending review request email messages, instead of using Main Site's. The implementation where the templates are configured must be published to the deployment zone before you reference the deployment zone in the interaction feed. If you omit this parameter, main_site is used. "secondary_site"
nickname no, unless nickname slaving is enabled Recommended. The customer's first name or nickname, captured when the customer creates an account. Used to personalize the email greeting. "Mary" or "mary75"
orderId yes The unique ID of the order. "55555"
shipping no The cost of shipping the order. "10.00"
shippingDate

no

 

Optional. Used instead of the transaction date to determine when Bazaarvoice sends the review requests. Must be in the following format: YYYY-MM-dd (e.g., 2014-12-21)
shippingDelay no

Optional. Used to increase the time (in days) between the transaction date and the date Bazaarvoice sends the review requests. This can be useful if you expect delayed fulfillment.

Note: You can use either shippingDate or shippingDelay, but should not use both.
"25"
state no The customer's state. "TX"
tax no The amount of tax applied to the order. "1.44"
total yes The total amount of the order. "40.84"
userId no, unless using site authentication

Recommended.userId must match the userToken (user id), which is passed to Bazaarvoice during the review submission process. Can be omitted if an ID is not created, as with guest purchasers.

Note: Ensure your review request configuration worksheet reflects this accurately.
"7448dc2"

Item parameters

Parameter Required Description Example
category no

Recommended. Product category.

Important: Should match the value you provide to Bazaarvoice in the product catalog.
"Shirts"
imageURL no

Highly recommended. Link to the product image. If omitted, we will retrieve the value from our database by matching the sku parameter to the product ExternalId sent in your product catalog.

Important: The URL specified for the imageURL parameter must be a full, absolute URL and not a relative path.
"http://www.test.com/1.jpg"
name no

Recommended. Product name.

Required if product ExternalId does NOT exist in our database. Otherwise, item is excluded from email.

Important: Should match the value you provide to Bazaarvoice in the product catalog.
"Black t-shirt"
price yes

Product price used to sort products in the review request by price.

Important: Must include only two (2) decimal places and no currency symbol.
"13.42"
quantity yes Purchase quantity. "4"
shippingDate

no

 

Optional Used instead of the transaction date to determine when Bazaarvoice sends the review requests. Must be in the following format: YYYY-MM-dd (e.g., 2014-12-21)
shippingDelay no

Optional. Used to increase the time (in days) between the transaction date and the date Bazaarvoice sends the review requests. This can be useful if you expect delayed fulfillment.

Note: You can use either shippingDate or shippingDelay, but should not use both.
"25"
sku yes

This is the Bazaarvoice product external ID. Sometimes this is a SKU code, but often it is some other product ID. It is used specifically with Bazaarvoice to uniquely identify your products.

Important: It MUST match the product ExternalId that is sent to Bazaarvoice in your product catalog. If the ID you set for the sku parameter is not in your product catalog, the product will NOT be included in the review request email message.
"2245"

Required vs. recommended parameters

At a minimum, you must include the following parameters:

  • items
  • email
  • phonenumber
  • userId—Include if your site does not support guest purchasers, or if you are not configured for hosted authentication. Contact Bazaarvoice if you are unsure about your configuration.
  • nickname—Include if you want to personalize your review requests with a name in the greeting such as, "Tell us what you think, , where is the name you use to address the user in the email.

In order to drive volume, Bazaarvoice highly recommends you include as much data as available to support current and future review request features.

Ranking products by price in a review request benefits user engagement. If you want your company's review requests to follow this format, you must send Bazaarvoice your price information. Other information you send can improve user experience.

Test transaction events using the Transactions monitoring tool

You can monitor and troubleshoot live transaction event data using the Transactions monitoring tool in BV Portal.

Note: The Transactions monitoring tool provides data about parameters that aren't in the BV Pixel v1 schema, such as discounts for items and orders. Contact Bazaarvoice Support if you want to upgrade to the latest schema.

Implement Analytics for API tags for ROI measurement

Note: The Analytics for API tags ConversionTransaction, PIIConversionTransaction, and Conversion together perform the same functions as the BV Pixel.  If you've already implemented the BV Pixel v1, it is not necessary to change your implementation to use these tags.

You can configure these tags for either transactional or non-transactional conversions using the code samples provided on this page. You can also view reference information for each tag using the links below:

Transactional conversion tagging

The following code example shows how ConversionTransaction and PIIConversionTransaction are used together for transactional conversion pages.

var TransactionData = {
        clientID: 'example_client_name',
        environment: 'staging',
        dc: "custom_dc",
        host: "bazaarvoice.com",
        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",
        deliveryDate: '2011-01-21T11:36:47.384',
        items: [
            {
                sku: '1234567-1',
                name: 'bunny hat',
                imageUrl: "http://bazaarvoice.com/bogusData/hats/1234567-1.gif",
                category: "hats",
                quantity: '1',
                price: "50.00"
 
            },
            {
                sku: '1234567-2',
                name: 'zombie hat',
                imageUrl: "http://bazaarvoice.com/bogusData/hats/1234567-2.gif",
                category: "hats",
                quantity: '1',
                price: "50.00"
            }
        ]
    };
    _bvapiq.push(['ConversionTransaction', TransactionData]);
    _bvapiq.push(['PIIConversionTransaction', TransactionData]);

Non-transactional conversion tagging

The following code example shows how Conversion is used for non-transactional conversion pages.

var ConversionData = {
        clientID: 'example_client_name',
        environment: 'staging',
        dc: "custom_dc",
        host: "bazaarvoice.com",
        city: 'Exampleville',
        state: 'Texas',
        country: 'USA',
        label: 'A conversion testing operation',
        value: 1,
        type: 'TestConversion'
    };
    _bvapiq.push(['Conversion', ConversionData]);