BV Pixel v1

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

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
You must also add a small snippet of Javascript to these pages, which sends data to Bazaarvoice via SSL (encrypted for security).
- For transactional conversion tagging (order pages), follow the add transaction tagging steps
  Or
- For non-transactional conversion tagging (page conversion events such as sign-ups or contact forms), follow the add non-transactional tagging steps

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

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 review request email messages.	A valid email address, formatted correctly
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 request. 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"

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

Parameter	Required	Description	Example
type	yes	Type of conversion that is taking place. You define the values of this parameter.	"StoreLocator" or "Download"
label	no	Descriptive label to apply to the conversion.	"ProductPage" or "ProductSpecification-1234.pdf"
value	no	Value 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]);

Pop out

Ratings & Reviews

Learn

Implement

Collect content

Product catalog

Display content

Manage content

Analyze data

View insights

Create reports

Analytics for API

Integrate analytics

BV Pixel v1

Implementing BV Pixel v1 (`bvapi.js`)

Implementing the BV Pixel on your transaction and conversion pages

Add the bvapi.js JavaScript tag

Add BV Pixel v1 transaction tagging

Transaction parameters

Items parameters

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

Conversion parameters for the BV Pixel v1

PII data

Personally identifiable information (PII)

Review request interaction parameters

Item parameters

Required vs. recommended parameters

Test transaction events using the Transactions monitoring tool

Implement Analytics for API tags for ROI measurement

Transactional conversion tagging

Non-transactional conversion tagging

Select your language:

Pop out

Ratings & Reviews

Learn

Implement

Collect content

Product catalog

Display content

Manage content

Analyze data

View insights

Create reports

Analytics for API

Integrate analytics

Implementing BV Pixel v1 (bvapi.js)

Implementing the BV Pixel on your transaction and conversion pages

Add the bvapi.js JavaScript tag

Add BV Pixel v1 transaction tagging

Transaction parameters

Items parameters

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

Conversion parameters for the BV Pixel v1

PII data

Personally identifiable information (PII)

Review request interaction parameters

Item parameters

Required vs. recommended parameters

Test transaction events using the Transactions monitoring tool

Implement Analytics for API tags for ROI measurement

Transactional conversion tagging

Non-transactional conversion tagging

Support

Feedback

Language

Print

Toggle dropdowns

Remove highlights

Implementing BV Pixel v1 (`bvapi.js`)