Note: You must implement Analytics for API on a whitelisted domain. Bazaarvoice manages the domain allowlist (sometimes called a "whitelist") internally. If you are in the implementation stage of a project, contact your Bazaarvoice implementation team to request changes to the allowlist. If you are in the support stage, contact Bazaarvoice Support to request changes.

Perform the following steps to configure the Signal tags and templates:

  1. Add events to trigger tags.

    Bazaarvoice tested and approved these events, so their use is highly recommended.  Although these recommended events are not required, their configurations are specific. Use caution if you intend to change them.

    Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

    In Signal's user interface, the events are conditional events used in the firing rules of a tag.

    Event Name

    Definition

    Used by

    bvConversion

    		Trigger: Click Selector: .bvConversionConversion (non-commerce)

    Multiple conversions will require a different Selector and Event Name for each feature type.
    For example: bvConversionCatalog (Selector .bvConversionCatalog),
    bvConversionLocator (Selector .bvConversionLocator).

    bvFeature

    		Trigger: Click Selector: .bvFeatureFeatureUsed

    Multiple features used will require a different Selector and Event Name for each feature type.

    For example: bvFeatureSort (Selector .bvFeatureSort), bvFeaturePaginate (Selector .bvFeaturePaginate)

    bvViewRawEvent

    		Trigger: load, scroll, resize Selector: windowFeatureUsedInView

    bvTransaction

    		Trigger: Click Selector: .bvTransactionConversionTransaction and PIIConversionTransaction

    bvViewedUGC

    		Trigger: bvViewedUGC Selector: windowFeatureUsedViewedUGC

    onLoad

    		Trigger: load Selector: windowPageViewProduct and PageViewCategory

    HTML and user interface elements in Signal initiate click-triggered events, which then trigger the associated tag. In some cases, such as ConversionTransaction and PIIConversionTransaction, the tag triggers on a page load, rather than by selecting a button.

  2. Complete a data mapping that contains relevant and required information for the tags.

    Datum Names used in your data mapping can be changed for your use case. The connection to data on your product pages is determined by how data is organized on each page.

    Datum Name

    Data Description

    Average Rating

    The average star rating for this product.

    Tag support:

    • PageViewProduct (optional)

    Brand Name

    Client-centric brand name to which the product belongs, if available.

    Tag support:

    • FeatureUsed (optional)
    • FeatureUserdInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewProduct (optional)

     

    Category (key)

    Category key for items in the JSON object that should reflect the exact key name in the JSON object.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Category ID

    Client-centric ID of the category being viewed. This ID is unique within your product catalog.

    Tag support:

    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewCategory (required)
    • PageViewProduct (optional)

    City

    The city to associate with the event.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Client ID

    Your Bazaarvoice client ID. Typically a constant in the template.

    Tag support:

    • Conversion (required)
    • ConversionTransaction (required)
    • FeatureUsed (required)
    • FeatureUsedInView (required)
    • FeatureUsedViewedUGC (required)
    • PageViewCategory (required)
    • PageViewProduct (required)
    • PIIConversionTransaction (required)

    Conversion Type

    The type of conversion that is taking place. A separate Conversion tag needs to be created for each conversion type.

    Tag support:

    • Conversion (required)

    Conversion Value

    The numerical value to attribute to the conversion.

    Tag support:

    • Conversion (required)

    Currency Code

    ISO 4217 alphabetic currency code.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Country

    The country associated with the event.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Debounce Period

    The time period in milliseconds that is enforced between debounced events. Typically a constant value, default is 250ms.

    Tag support:

    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)

    Delivery Date

    Used to schedule the delivery of the email. Bazaarvoice will send the email x days from this date per your emailDelayDays specification. If this is not specified, the current date/time will be used automatically.

    Tag support:

    • PIIConversionTransaction (optional)

    Detail 1

    First-level detail for the feature. 

    Bazaarvoice recommends that the fields filter, sort, and paginateare tagged and labeled in this field.

    Tag support:

    • FeatureUsed (required)

    Detail 2

    Second-level detail for the feature. 

    Tag support:

    • FeatureUsed (optional)

    Display Code

    Display code or other UI variant identifier. If you are not familiar with this code, please contact your Support Engineer.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewCategory (optional)
    • PageViewProduct (optional)
    • PIIConversionTransaction (optional)

    E-Mail

    The email address of the user.

    Tag support:

    • PIIConversionTransaction (required)

    Feature Name

    Name of the feature used, for example sort, paginate, InView. A separate FeatureUsed tag needs to be created for each feature used.

    Tag support:

    • FeatureUsed (required)

    Host Name

    Hostname for the page from which the event was sent. If no value is specified, this defaults to window.location.host.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewCategory (optional)
    • PageViewProduct (optional)
    • PIIConversionTransaction (optional)

    Image URL (key)

    Image URL key for items in the JSON object. This should reflect the exact key name in the JSON object.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    In-View Time

    How long the user-generated content (UGC) container must be visible, in milliseconds, for it to be considered "viewed." Typically a constant value, defaulting to 5000ms (5 seconds).

    Tag support:

    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)

    Items Object

    This is a JSON or JSON-like object that is referenced by the data dictionary. This referenced object contains the item-level information for the order.

    Tag support:

    • ConversionTransaction (required)
    • PIIConversionTransaction (required)

    Label

    A descriptive label to apply to the conversion.

    Tag support:

    • Conversion (optional)

    Min Visible Pixels

    The minimum number of vertical pixels of the UGC container that must be displayed for UGC to be considered visible. Typically a constant value. Default is 100 pixels.

    Tag support:

    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)

    Num Answers

    Number of answers for this product. 

    Tag support:

    • PageViewProduct (optional)

    Num Questions

    Number of questions for this product.

    Tag support:

    • PageViewProduct (optional)

    Num Reviews

    Number of reviews for this product. 

    Tag support:

    • PageViewProduct (optional)

    Order ID

    The unique ID of the order.

    Tag support:

    • ConversionTransaction (required)
    • PIIConversionTransaction (required)

    Order Total

    The total amount of the order.

    Tag support:

    • ConversionTransaction (required)
    • PIIConversionTransaction (required)

    Percent Recommended

    Percentage of users who would recommend this product. The value should be between 0 and 100.

    Tag support:

    • PageViewProduct (optional)

    Price (key)

    Price key for items in the JSON object and should reflect the exact key name in the JSON object.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Product ID

    Client-centric product ID for features used in the context of a product. Unique within your product catalog.

    Tag support:

    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewProduct (required)

    Product Name (key)

    Product Name key for items in the JSON object and should reflect the exact key name in the JSON object.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Quantity (key)

    Quantity key for items in the JSON object and should reflect the exact key name in the JSON object.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Referring URL

    Referrer of the page from which the event was sent, if available. The default is document.referrer.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewCategory (optional)
    • PageViewProduct (optional)
    • PIIConversionTransaction (optional)

    Root Category ID

    Client-centric category ID of the root category relative to the category identified by the categoryId property value. This ID is unique within your product catalog.

    Tag support:

    • FeatureUsed (optional)
    • FeatureUsedInView (optional)
    • FeatureUsedViewedUGC (optional)
    • PageViewCategory (optional)
    • PageViewProduct (optional)

    Shipping Amount

    The cost of shipping for the order.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    SKU (key)

    SKU or Product ID key for items in the JSON object and should reflect the exact key name in the JSON object.

    Note: 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 (formerly post-interaction email or PIE).

    Tag support:

    • ConversionTransaction (required)
    • PIIConversionTransaction (required)

    State

    The state to associate with the event.

    Tag support:

    • Conversion (optional)
    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    Tax Amount

    The amount of tax applied to the order.

    Tag support:

    • ConversionTransaction (optional)
    • PIIConversionTransaction (optional)

    UGC Container ID

    The DOM ID of the container that holds Bazaarvoice UGC. This informs the tag which DOM object to watch for visibility.

    Tag support:

    • FeatureUsedInView (required)
    • FeatureUsedViewedUGC (required)

    User ID

    The unique ID of the user.

    Tag support:

    • PIIConversionTransaction (optional)

    User Nickname

    The first name or nickname of the user.

    Tag support:

    • PIIConversionTransaction (optional)

    Zip Code

    The postal code to associate with the transaction.

    Tag support:

    • PIIConversionTransaction (optional)
  3. Fill in the tag templates with data mappings.
  4. Fill in the tag triggering event.
Note: You can use the analytics tags as the BV Pixel by using Signal's BVConversion and BVTransaction tags.

Conversion tag

Conversion indicates a non-commercial conversion. Conversions keep track of user activities that do not directly generate revenue but are still valuable, such as using a dealer locator page or ordering a free catalog.

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

Refer to Implementing the BV Pixel with analytics tags for full implementation examples.

Event binding

Conversion can be triggered explicitly by the conversion button, as shown in the following example:

<button onclick="_bvapiq.push(['Conversion', ConversionData]);">Test Conversion</button>

Data and mapping

FieldBuilt-in MappingDescription
clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

typeconversion.type, conversion.category.type

Type of conversion that is taking place.

Priority: Required

valueconversion.value, conversion.attributes.value

Value attributed to the conversion.

Priority: Required

cityconversion.city, conversion.profile.address.cityCity associated with the transaction.

Priority: Recommended

countryconversion.country, conversion.profile.address.countryCountry associated with the transaction.

Priority: Recommended

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

labelconversion.label, conversion.attributes.label

Descriptive label to apply to the conversion.

Priority: Recommended

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

stateconversion.state, conversion.profile.address.state

State associated with the transaction.

Priority: Recommended

host

page.host, page.pageInfo.hostName

Hostname for the page from which the event was sent.

Default value: window.location.hostname

Priority: Optional

ConversionTransaction tag

ConversionTransaction indicates a commercial transaction or conversion. Conversion transactions keep track of purchases and are a key component in calculating conversion lift.

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

Refer to Implementing the BV Pixel with analytics tags for full implementation examples.

Event binding

Include the ConversionTransaction tag on a confirmation page load, as shown in the following example:

<script>
    window._bvapiq = window._bvapiq || [];
    _bvapiq.push(['ConversionTransaction', TransactionData]);
    $.getScript('//magpie-static.ugc.bazaarvoice.com/magpie-api/1.4/
bvAnalyticsAPITracker.min.js.gz');
</script>

Data and mapping

FieldBuilt-in MappingDescription
clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

orderIdtransaction.orderId, transaction.transactionID

Unique ID of the order.

Priority: Required

sku

items[].sku, items[].productInfo.sku

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.

Note: It MUST match the product's 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.

Priority: Required

totaltransaction.total, transaction.total.transactionTotal

Total amount of the order.

Priority: Required

cityconversion.city, conversion.profile.address.city

City associated with the transaction.

Priority: Recommended

countryconversion.country, conversion.profile.address.country

Country associated with the transaction.

Priority: Recommended

currencytransaction.currency, transaction.total.currency

ISO 4217 alphabetic currency code.

Priority: Recommended

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

labelconversion.label, conversion.attributes.label

Descriptive label to apply to the conversion.

Priority: Recommended

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

stateconversion.state, conversion.profile.address.state

State associated with the transaction.

Priority: Recommended

categoryitems[].category, items[].category.primaryCategory

Product category.

Priority: Optional

hostpage.host, page.pageInfo.hostName

Hostname for the page from which the event was sent.

Priority: Optional

imageUrlitems[].imageUrl, items[].productInfo.productImage

Product image URL.

Priority: Optional

nameitems[].name, items[].productInfo.productName

Product name.

Priority: Optional

priceitems[].price, items[].price.basePrice

Product price.

Priority: Optional

quantityitems[].quantity

Purchase quantity.

Priority: Optional

shippingtransaction.shipping, transaction.total.shipping

Cost of shipping for the order.

Priority: Optional

taxtransaction.tax, transaction.total.taxAmount

Amount of tax applied to the order.

Priority: Optional

FeatureUsed tag

FeatureUsed indicates user interaction with the UGC container and controls. This tag should be used for features such as:

  • Filter
  • Sort
  • Paginate

Event binding

Attach the FeatureUsed tag to the click event of any user interface element, as shown in the following example:

    <button onclick="_bvapiq.push(['FeatureUsed', {
        clientID: 'testClient',
    bvProduct: 'AskAndAnswer',  
        environment: 'staging',
        dc: 'custom_DC',
        name: 'Feature_Button',
        brand: 'Test Brand',
        productId: '1234567-bunnyhat',
        categoryId: 'hats',
        detail1: 'First feature detail',
        detail2: 'Second feature detail'
    }]);">Feature Button</button>

Data and mapping

FieldBuilt-in MappingDescription
brandproduct.brand, product.productInfo.brandID

Client-centric brand name to which the product belongs, if available.

Priority: Recommended

bvProductbvProduct

Name of the Bazaarvoice product for the event being sent. Possible values include RatingsAndReviews and AskAndAnswer.

Priority: Required

categoryIdproduct.categoryId, product.category.primaryCategory

Client-centric ID of the category being viewed.

Unique within the client's product catalog.

Priority: Recommended

clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

detail1event.detail1, event[].detail1, event.category.subDetail1, event[].category.subDetail1, (attribute) bvDetail1

First-level sub-detail for the feature.

Bazaarvoice recommends that the fields filter, sort, and paginate are tagged and labeled in this field.

Feature usage metrics automatically aggregate by feature name, detail1, and detail2 (in that order), so you can extract hierarchical metrics given carefully crafted detail attributes.

Priority: Required

detail2event.detail2, event[].detail2, event.category.subDetail2, event[].category.subDetail2, (attribute) bvDetail2

Second-level sub-detail for the feature. See "detail1." Default = _bvGetState("event.detail2").

Priority: Recommended

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

host

page.host, page.pageInfo.hostName

Hostname for the page from which the event was sent.

Default value: window.location.hostname

Priority: Optional

nameevent.name, event[].name, (attribute) bvName

Name of the feature used, for example: "sort", "paginate", "InView."

Priority: Required

productIdproduct.productId, product.productInfo.productID

Client-centric product ID for features used in the context of a product.

Unique within the client's product catalog.

Note: It MUST match the product's ExternalId in your product catalog.

Priority: Required

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

rootCategoryIdproduct.rootCategoryId, product.category.rootCategory

Client-centric category ID of the root category relative to the category identified by the <categoryId> property value.

Unique within the client's product catalog.

Priority: Optional

FeatureUsedInView tag

FeatureUsedInView indicates that UGC is visible on the page. Since this tag is triggered when UGC is first made visible, users have not yet had the opportunity to interact with the content. This tag will only be triggered once each page loads.

Event binding

FeatureUsedInView is paired with FeatureUsedViewedUGG and executed on page load. This tag binds to the bvViewedUGC event as shown in the following example:

    var InViewData = {
        clientID: 'testClient',
    bvProduct: 'RatingsAndReviews', 
        environment: 'staging',
        bvAttributes: {
            minVisiblePixels: 100,
            debouncePeriodMs: 250,
            inviewTime: 5000,
            containerId: 'bvUGC'
        },
        dc: "custom_DC",
        productId: '1234567-bunnyhat',
        brand: 'Test Brand',
        categoryId: 'hats',
        rootCategoryId: 'garments'
    };
    _bvapiq.push(['FeatureUsedInView', InViewData]);
    $(window).on('resize, scroll', function(event) {_bvapiq.push(['FeatureUsedInView', InViewData]); });
    $(window).on('bvViewedUGC', function(event) {_bvapiq.push(['FeatureUsedViewedUGC', InViewData]); });
Note: This tag binds to high-volume events. Code internal to the tag filters events, so that tests are not performed on every occurrence of an event. This filtering limits test frequency to prevent excessive CPU load.

Data and mapping

FieldBuilt-in MappingDescription
brandproduct.brand, product.productInfo.brandIDClient-centric brand name to which the product belongs, if available.

Priority: Recommended

bvProductbvProduct

Name of the Bazaarvoice product for the event being sent. Possible values include RatingsAndReviews and AskAndAnswer.

Priority: Required

categoryIdproduct.categoryId, product.category.primaryCategory

Client-centric ID of the category being viewed.

Unique within the client's product catalog.

Priority: Recommended

clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

debouncePeriodMsbvAttributes.dbouncePeriodMs

Time period in milliseconds that is enforced between debounced events.

Default value: 250

Priority: Optional

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

host

page.host, page.pageInfo.hostName

Hostname for the page from which the event was sent.

Default value: window.location.hostname

Priority: Optional

productIdproduct.productId, product.productInfo.productID

Client-centric product ID for features used in the context of a product.

Unique within the client's product catalog.

Note: It MUST match the product's ExternalId in your product catalog.

Priority: Required

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

rootCategoryIdproduct.rootCategoryId, product.category.rootCategory

Client-centric category ID of the root category relative to the category identified by the <categoryId> property value.

Unique within the client's product catalog.

Priority: Optional

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.

bvAttributeDescription
containerId

DOM ID of the container that holds UGC items.

Priority: Required

debouncePeriodMs

Time period in milliseconds that is enforced between debounced events.

Default value: 250

Priority: Optional

inviewTime

How long the UGC container must be visible, in milliseconds, for it to be considered "viewed."

Default value: 5000

Priority: Optional

minVisiblePixels

Minimum number of vertical pixels of the UGC container that must be displayed for UGC to be considered visible.

Default value: 100

Priority: Optional

FeatureUsedViewedUGC tag

Five seconds, or a client-defined delay, after the FeatureUsedViewedUGC event is triggered, a bvViewedUGC event occurs. The ViewedUGC tag is triggered if UGC is still visible in the display window when this event is processed. ViewedUGC only triggers once each page loads. If UGC is not viewable when ViewedUGC tests it, the tag will re-arm the bvViewedUGC event and try again later.

Event binding

FeatureUsedViewedUGG is paired with FeatureUsedInView and is executed on page load. This tag binds to the bvViewedUGC event as shown in the following example:

    var InViewData = {
        clientID: 'testClient',
    bvProduct: 'Sampling', 
        environment: 'staging',
        bvAttributes: {
            minVisiblePixels: 100,
            debouncePeriodMs: 250,
            inviewTime: 5000,
            containerId: 'bvUGC'
        },
        dc: "custom_DC",
        productId: '1234567-bunnyhat',
        brand: 'Test Brand',
        categoryId: 'hats',
        rootCategoryId: 'garments'
    };
    _bvapiq.push(['FeatureUsedInView', InViewData]);
    $(window).on('resize, scroll', function(event) {_bvapiq.push(['FeatureUsedInView', InViewData]); });
    $(window).on('bvViewedUGC', function(event) {_bvapiq.push(['FeatureUsedViewedUGC', InViewData]); });

Data and mapping

The data and mapping used by FeatureUsedViewedUGC matches the data and mapping used by FeaturesUsedInView. These two tags are essentially two versions of the same event.

FieldBuilt-in MappingDescription
brandproduct.brand, product.productInfo.brandIDClient-centric brand name to which the product belongs, if available.

Priority: Recommended

bvProductbvProduct

Name of the Bazaarvoice product for the event being sent. Possible values include RatingsAndReviews and AskAndAnswer.

Priority: Required

categoryIdproduct.categoryId, product.category.primaryCategory

Client-centric ID of the category being viewed.

Unique within the client's product catalog.

Priority: Recommended

clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

debouncePeriodMsbvAttributes.dbouncePeriodMs

Time period in milliseconds that is enforced between debounced events.

Default value: 250

Priority: Optional

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

hostpage.host, page.pageInfo.hostNameHostname for the page from which the event was sent.

Default value: window.location.hostname

Priority: Optional

productIdproduct.productId, product.productInfo.productID

Client-centric product ID for features used in the context of a product.

Unique within the client's product catalog.

Note: It MUST match the product's ExternalId in your product catalog.

Priority: Required

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

rootCategoryIdproduct.rootCategoryId, product.category.rootCategory

Client-centric category ID of the root category relative to the category identified by the <categoryId> property value.

Unique within the client's product catalog.

Priority: Optional

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.

bvAttributeDescription
containerId

DOM ID of the container that holds UGC items.

Priority: Required

debouncePeriodMs

Time period in milliseconds that is enforced between debounced events.

Default value: 250

Priority: Optional

inviewTime

How long the UGC container must be visible, in milliseconds, for it to be considered "viewed."

Default value: 5000

Priority: Optional

minVisiblePixels

Minimum number of vertical pixels of the UGC container that must be displayed for UGC to be considered visible.

Default value: 100

Priority: Optional

PageViewCategory tag

PageViewCategory indicates that a user has loaded a product category page. The PageViewCategory tag should be triggered on every category page, on every load.

Event binding

PageViewCategory should be enabled on the analytics JavaScript load, so the tag is triggered immediately upon page load, as shown in the following code:

window._bvapiq = window._bvapiq || [];
_bvapiq.push(['PageViewCategory', CategoryData]);
$.getScript('http://magpie-static.ugc.bazaarvoice.com/magpie-api/1.2/bvAnalyticsAPITracker.js')

Data and mapping

FieldBuilt-in MappingDescription
clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

categoryIdproduct.categoryId, product.category.primaryCategory

Client-centric ID of the category being viewed.

Unique within the client's product catalog.

Priority: Recommended

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value:window.navigator.language

Priority: Required

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value:'prod'

Priority: Recommended

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value:document.referrer

Priority: Recommended

rootCategoryIdproduct.rootCategoryId, product.category.rootCategory

Client-centric category ID of the root category relative to the category identified by the <categoryId> property value.

Unique within the client's product catalog.

Priority: Recommended

hostpage.host, page.pageInfo.hostNameHostname for the page from which the event was sent.

Default value:window.location.hostname

Priority: Optional

Data examples

var ProductData = {
    clientID: 'example_client_name',
    environment: 'staging',
    page: {
        pageInfo: {
            region: "custom_dc",
            hostName: "bazaarvoice.com"
        }
    },
    product: {
        category: {
            categoryID: 'testCategory',
            rootCategory: 'testing'
        }
    }
};


var ProductDataFlat = {

    clientID: 'example_client_name',
    environment: 'staging',
    dc: "custom_dc",
    host: "bazaarvoice.com",
    categoryId: 'testCategory',
    rootCategoryId: 'testing'
};

PageViewProduct tag

PageViewProduct indicates that a user has loaded a product page. The PageViewProduct tag should be triggered on every product page and every load. It should not be hidden behind a tab or otherwise prevented from triggering on page load. This tag works in conjunction with the ConversionTransaction tag to power much of Bazaarvoice’s internal reporting.

Event binding

As shown in the following example, loading the analytics tag’s JavaScript enables PageViewProduct, so the tag is triggered immediately upon page load:

    _bvapiq.push(['PageViewProduct', {
        clientID: 'testClient',
    bvProduct: 'RatingsAndReviews', 
        environment: 'staging',
        dc: "custom_DC",
        productId: '1234567-bunnyhat',
        brand: 'Test Brand',
        categoryId: 'hats',
        rootCategoryId: 'garments',
        numReviews: 1,
        numQuestions: 0,
        numAnswers: 0,
        avgRating: 5.0,
        percentRecommended: 100
    } ]);

Data and mapping

FieldBuilt-in MappingDescription
avgRatingproduct.avgRating, product.attributes.ugc.averageRating

Average star rating for this product.

Include if this value is shown to users, even if the value is 0; otherwise, do not include this field.

Priority: Recommended

brandproduct.brand, product.productInfo.brandIDClient-centric brand name to which the product belongs, if available.

Priority: Recommended

bvProductbvProduct

Name of the Bazaarvoice product for the event being sent. Possible values include RatingsAndReviews and AskAndAnswer.

Priority: Required

categoryIdproduct.categoryId, product.category.primaryCategory

Client-centric ID of the category being viewed.

Unique within the client's product catalog.

Priority: Recommended

clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

hostpage.host, page.pageInfo.hostNameHostname for the page from which the event was sent.

Default value: window.location.language

Priority: Optional

numAnswersproduct.numAnswers, product.attributes.ugc.numAnswers

Number of answers for this product.

Include if this value is shown to users, even if the value is 0; otherwise, do not include this field.

Priority: Required if bvProduct:'AskAndAnswer'

numQuestionsproduct.numQuestions, product.attributes.ugc.numQuestions

Number of questions for this product.

Include if this value is shown to users, even if the value is 0; otherwise, do not include this field.

Priority: Required if bvProduct:'AskAndAnswer'

numReviewsproduct.numReviews, product.attributes.ugc.numReviews

Number of reviews for this product.

Include if this value is shown to users, even if the value is 0; otherwise, do not include this field.

Priority: Required if bvProduct:'RatingsandReviews'

percentRecommendedproduct.percentRecommended, product.attributes.ugc.percentRecommended

Percentage of users who would recommend this product. The value should be between 0 and 1.

Include if this value is shown to users, even if the value is 0; otherwise, do not include this field.

Priority: Optional

productIdproduct.productId, product.productInfo.productID

Client-centric product ID for features used in the context of a product.

Unique within the client's product catalog.

Note: It MUST match the product's ExternalId in your product catalog.

Priority: Required

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

rootCategoryIdproduct.rootCategoryId, product.category.rootCategory

Client-centric category ID of the root category relative to the category identified by the <categoryId> property value.

Unique within the client's product catalog.

Priority: Recommended

PIIConversionTransaction tag

PIIConversionTransaction indicates a commercial conversion occurred that includes personal identifying information (PII), but is otherwise a duplicate ConversionTransaction. This tag is sent through different channels and to a different endpoint to satisfy privacy concerns. The collected PII information is transmitted, stored, and used only for review requests.

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

Refer to Implementing the BV Pixel with analytics tags for full implementation examples.

Event binding

Include the PIIConversionTransaction tag on a confirmation page load, as shown in the following example:

<script>
    window._bvapiq = window._bvapiq || [];
    _bvapiq.push(['PIIConversionTransaction', TransactionData]);
    $.getScript('//magpie-static.ugc.bazaarvoice.com/magpie-api/1.4/bvAnalyticsAPITracker.min.js.gz');
</script>

Data and mapping

FieldBuilt-in MappingDescription
clientIDclientID

Name of the Bazaarvoice client on whose behalf the event was sent.

This is the same value as the Workbench login.

Priority: Required

emailtransaction.email, transaction.profile.profileInfo.email

User's email address.

Priority: Required

orderIdtransaction.orderId, transaction.transactionID

Unique ID of the order.

Priority: Required

sku

items[].sku, items[].productInfo.sku

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.

Note: It MUST match the product's 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.

Priority: Required

totaltransaction.total, transaction.total.transactionTotal

Total amount of the order.

Priority: Required

userIdno, unless using site authentication

userId must match the userToken (user id) 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.

Priority: Recommended

cityconversion.city, conversion.profile.address.cityCity associated with the transaction.

Priority: Recommended

countryconversion.country, conversion.profile.address.countryCountry associated with the transaction.

Priority: Recommended

currencytransaction.currency, transaction.total.currency

ISO 4217 alphabetic currency code.

Priority: Recommended

dcpage.dc, page.pageInfo.region

Display code or other UI variant identifier. If you are not familiar with this code, contact your Support Engineer.

Default value: window.navigator.language

Priority: Required

environmentenvironment

Application environment from which the event was sent. prod is for production code. staging is for testing and debugging.

Default value: 'prod'

Priority: Recommended

nicknametransaction.nickname, transaction.profile.profileInfo.userName

User’s first name or nickname.

Priority: Recommended

refpage.ref, page.pageInfo.referringURLReferrer of the page from which the event was sent, if available.

Default value: document.referrer

Priority: Recommended

stateconversion.state, conversion.profile.address.state

State associated with the transaction.

Priority: Recommended

ziptransaction.zip, transaction.profile.address.postalCode

Postal code associated with the transaction.

Priority: Recommended

categoryitems[].category, items[].category.primaryCategory

Product category.

Priority: Optional

shippingDatetransaction.shippingDate, transaction.total.shippingDate

Used to schedule the delivery of the email. We will send the email x days from this date per your specification for emailDelayDays.

If this is not specified, the current date/time will be used automatically.

Must be in the following format: YYYY-MM-DDTHH:mm:ss.SSS.

Priority: Optional

hostpage.host, page.pageInfo.hostNameHostname for the page from which the event was sent.

Default value: window.location.hostname

Priority: Optional

imageUrlitems[].imageUrl, items[].productInfo.productImage

Product image URL.

Priority: Optional

nameitems[].name, items[].productInfo.productName

Product name.

Priority: Optional

priceitems[].price, items[].price.basePrice

Product price.

Priority: Optional

quantityitems[].quantity

Purchase quantity.

Priority: Optional

shippingtransaction.shipping, transaction.total.shipping

Cost of shipping for the order.

Priority: Optional

taxtransaction.tax, transaction.total.taxAmount

Amount of tax applied to the order.

Priority: Optional