Note: If you have 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 implementing maintenance-free PIE.

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. The data captured might include SKUs, email addresses, and postal addresses. These customer transaction details are required to implement maintenance-free PIE. 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 are interacting on your site, and to understand the value of your implementation.

Note: You must install the BV Pixel before you can use Bazaarvoice reports, 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).

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 whitelisted domain. Bazaarvoice manages the domain whitelist internally. Any changes to the whitelist 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 Client Care 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 maintenance-free post-interaction email (PIE).

  • 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 PIE interaction parameters for detailed descriptions of each property.
  • The conversion tagging method only applies to ROI measurement and cannot be used for maintenance-free PIE.
  • 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 maintenance-free post-interaction email (PIE). If you set up the BV Pixel to power maintenance-free PIE, 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 the PIE.A valid email address, formatted correctly
itemsyes, unless sending non-transactional PIERequired for transactional PIE. 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 PIEs 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 PIE 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 PIE 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 PIE.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 PIE. 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 PIE 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 PIE 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 PIE.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 PIE. 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 PIE message.
"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 maintenance-free PIE.

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 post-interaction email (PIE) message, helps increase content volume on your site.

Note: Non-commerce conversions currently do not trigger maintenance-free PIE.
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 maintenance-free PIE The customer's email address. A valid email address, formatted correctly
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 PIE 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.

PIE interaction parameters

Use the following interaction parameters when you are configuring maintenance-free PIE 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 PIE. A valid email address, formatted correctly
items yes, unless sending non-transactional PIE Required for transactional PIE. 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 PIEs 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 PIE 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 PIE 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 PIE. 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 PIE. 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 PIE 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 PIE 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 PIE. 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 PIE. 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 PIE message.
"2245"

Required vs. recommended parameters

At a minimum, you must include the following parameters:

  • items
  • email
  • 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 PIEs 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 PIE features.

Ranking products by price in a PIE benefits user engagement. If you want your company's PIEs 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 Client Care if you want to upgrade to the latest schema.