Tagging with the ROI beacon allows you to send useful data directly from your web pages to Bazaarvoice. The purpose of this beacon is to capture important interaction events by users, even if those interactions occur outside of Bazaarvoice products. Some examples of conversion events include:

  • Transactions: A user completed a purchase. The tag would be connected to the transaction confirmation or “Thank you” page. For more information, see the Adding the ROI beacon to transaction pages section.
  • Non-commerce conversion events: For non E-commerce web sites, a user launching the “store locator” feature is considered a conversion. This tag could be connected with the click handler for the store locator link or on the store locator results page. For more information, see the Adding the ROI beacon to conversion pages section.

Adding the ROI beacon to transaction pages

Implementing the ROI beacon requires 2 steps:

  • Include the Bazaarvoice BV API JavaScript file (bvapi.js) on the page.
  • Add a small snippet of JS code to the page which sends all data to Bazaarvoice via SSL (encrypted for security). This is called “interaction tagging”.

Including bvapi.js

Place the following code within the head element:

<script type="text/javascript"
    src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
</script>

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

Interaction tagging

Interaction tagging captures detailed information about a user’s interactions enabling ROI measurement.

The following is an example of the JavaScript snippet (“tag”) used for ROI measurement: Important:

  • Boldface properties are specific to ROI measurement. All others are used for maintenance-free PIE.
  • Letter case is important.
  • This code is a sample and should not be used as is. You need to add/remove properties and associated values as necessary for your specific application requirements.
  • See the tables that follow this code example for detailed descriptions of each property.

For transaction pages, supply the following data using the sample format:

{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://client.com/1.jpg"
        },
        {
            "sku" : "2246",
            "name" : "product name2",
            "imageURL" : "http://client.com/2.jpg"
        }
    ],
    "userId" : "7448dc2",
    "email" : "john@example.com",
    "nickname" : "john1981",
    "deliveryDate" : "2011-01-21T11:36:47.384",
    "locale" : "en_US"
});
{code}

Transaction parameters

Refer to the tables below for details about parameters, which are required vs. recommended. If a recommended parameter is not available on the page (such as userId for guest purchasers), 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:  ROI beacon can also be used to enable maintenance-free PIE. If you are interested in setting up the ROI beacon to power maintenance-free PIE, see the Maintenance-free PIE integration guide for more information about additional interaction parameter requirements.
Note:  All parameters are case sensitive and must be formatted correctly. Example:
correct: userId
incorrect: Userid  user_Id  userID  UserId
ParameterRequiredDescriptionExample
orderIdyesThe unique ID of the order. Required for ROI measurement. Used to measure lift in average number of orders for products where UGC is present."55555"
taxnoThe amount of tax applied to the order."1.44"
shippingnoThe cost of shipping the order."10.00"
totalyesThe total amount of the order. Required for ROI measurement. Used to generate standard ROI reports."40.84"
citynoThe customer's city."Austin"
statenoThe customer's state."TX"
countrynoThe customer's country."USA"
currencynoThe ISO 4217 alphabetic currency code of the order."USD"
itemsyesThe parameters associated with each item in the order. Required for ROI measurement.See table below.

Items parameters

ParameterRequiredDescriptionExample
skuyesThis is the BV product external ID. Sometimes this is a SKU code, but often it is some other product ID. It is used specifically with BV to uniquely identify your products. Required for ROI measurement.
Note:  The sku is the product's ExternalId as defined in the product feed you have provided to Bazaarvoice. This sku, ExternalId, and productId should all match for a given product. If these IDs don't match, our analytics engine cannot correlate consumer behavior to conversion.
"2245"
namenoProduct name. Recommended for ROI measurement. Can be used to generate reports by product name vs. sku/product ID.
Note:  Should match the value you provide to Bazaarvoice in the product feed.
"Black t-shirt"
categorynoProduct category. Recommended for ROI measurement.
Note:  Should match the value you provide to Bazaarvoice in the product feed.
"Shirts"
pricenoProduct price used to sort products in the PIE by price.
Note:  Must include only two (2) decimal places and no currency symbol.
"13.42"
quantitynoQuantity purchased. Recommended for ROI measurement. Quantity can be used to measure average lift in items per order when UGC is present."4"
imageURLnoLink to the product image, which is used to display the product image.
Note:   Should match the value you provide to Bazaarvoice in the product data feed. If you omit this value but provide a valid External ID, we pull the imageUrl from our database.
"http://client.com/product/image.jpg"

PII parameters used for PIE

The following parameters are considered to be personally identifiable information (PII). 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), helps to increase content volume on your site.

ParameterRequiredDescriptionExample
userIdno, unless using site authenticationThe unique ID of the user."7448dc2"
localenoTransaction locale. Use a two or four letter code. Format is [language_code]_[COUNTRY_CODE]. Used to send locale-specific PIE."de_DE" or "de"
emailno, unless tagging to enable maintenance-free PIEThe user's email address.A valid email address, formatted correctly
nicknameno, unless tagging to enable maintenance-free PIE and nickname slaving is enabledThe nickname of the user. The nickname is used to address the user in the PIE."Mary" or "mary75"

At a minimum you must include the following parameters for transactional PIE:

  • email and items are required
  • If your site does NOT support guest purchasers, or if you are NOT configured for hosted authentication (double-check with Bazaarvoice if you are unsure)
    • userId is required
  • If you want to personalize your PIEs with a name in the greeting such as, “Tell us what you think.”
    • nickname is required

In order to drive volume, we highly recommend you include as much data as available to support current and future features offered by Bazaarvoice.

It is beneficial for user engagement to rank the products within the PIE based on price. In order to do this, we must receive price information. Other information improves user experience and potentially allows for different templates to be used based on the data provided. The use of different templates is scheduled for a future version of PIE.

The recommended fields reflect setting the minimum parameters. The best practice would be to include data such as “Shipping date” and “Backordered” so that we might exclude the effected product from the PIE when this functionality becomes available.

PII data

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

  • email address
  • first name, last name
  • nickname, 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.

Note:  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.

Adding the ROI beacon to conversion pages

Implementing the ROI beacon requires 2 steps:

  1. Include the Bazaarvoice BV API JavaScript file (bvapi.js) on the page.
  2. Add a small snippet of JS code to the page which sends all data to Bazaarvoice via SSL (encrypted for security). This is called “interaction tagging”.

Place the following code within the head element:

<script type="text/javascript"
    src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
</script>

<!-- tagging code -->
<script type="text/javascript">
    $BV.SI.trackConversion({
        /* Conversion data goes here...
            See section, "Interaction tagging"
            below for details...
        */
    });
</script>
{code}

Interaction tagging

Conversion events accept 3 high-level parameters to help describe the type of conversion taking place. Here is an example of a conversion event where a user used a “store locator” feature by supplying their zip code.

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}

Refer to the tables below for details on parameters, which are required vs. recommended. If a recommended parameter is not available on the page (such as userId for guest purchasers), 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.

Conversion parameters

ParameterRequiredDescriptionExample
typeyesThe type of conversion. You define the values of this parameter."StoreLocator" or "Download"
labelnoA descriptive label to apply to the conversion."ProductPage" or "ProductSpecification-1234.pdf"
valueyesA value to attribute to the conversion."78701" or "1"

PII parameters used for PIE

The following parameters are considered to be personally identifiable information (PII). 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), helps to increase content volume on your site.

ParameterRequiredDescriptionExample
userIdno, unless using site authenticationThe unique ID of the user."7448dc2"
localenoTransaction locale. Use a two or four letter code. Format is [language_code]_[COUNTRY_CODE]. Used to send locale-specific PIE."de_DE" or "de"
emailno, unless tagging to enable maintenance-free PIEThe user's email address.A valid email address, formatted correctly
nicknameno, unless tagging to enable maintenance-free PIE and nickname slaving is enabledThe nickname of the user. The nickname is used to address the user in the PIE."Mary" or "mary75"

At a minimum you must include the following parameters for transactional PIE:

  • email and items are required
  • If your site does NOT support guest purchasers, or if you are NOT configured for hosted authentication (double-check with Bazaarvoice if you are unsure)
    • userId is required
  • If you want to personalize your PIEs with a name in the greeting such as, “Tell us what you think.”
    • nickname is required

In order to drive volume, we highly recommend you include as much data as available to support current and future features offered by Bazaarvoice.

PII data

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

  • email address
  • first name, last name
  • nickname, 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.

Note:  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.