Refer to the following advanced integration tasks:

Loading the bvapi.js API asynchronously

All Bazaarvoice content except the API loader file bvapi.js is loaded asynchronously.

If you must load content asynchronously, do not include the bvapi.js script tag directly in your HTML pages. Include the bvapi.js script in one of the following script blocks instead:

  • If you use jQuery, include the following block:

    <script type="text/javascript">
    var bvapiUrl = window.location.protocol + "//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js";
    
    window.loadBazaarvoiceApi = function(callback) {
        if (window.$BV) {
            callback();
        } else {
            $.ajax({
                url: bvapiUrl,
                cache: true,
                dataType: "script",
                success: function() {
                    $($BV.docReady);
                    callback();
                }
            });
        }
    };
</script>

  • If you do not use jQuery, include the following JavaScript:

    <script type="text/javascript">
    (function() {
        var bvapiUrl = window.location.protocol + "//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js"; 
    
        function getScript(url, callback) {
            var head = document.getElementsByTagName("head")[0] ||
                document.documentElement,
                script = document.createElement("script");
            script.src = url;
            script.type = "text/javascript";
            script.charset = "utf-8";
            script.setAttribute("async", "async");
            script.onload = script.onreadystatechange = function () {
                if (!this.readyState || this.readyState === "loaded" ||
                    this.readyState === "complete") {
                    script.onload = script.onreadystatechange = null;
                    callback();
                }
            };
            head.insertBefore(script, head.firstChild);
        }
    
        // work around Firefox 3.0, 3.5 lack of document.readyState
        // property.
        // Note: Because of this workaround, the <script> fragment must
        // be included within the <head> or <div> element so that it
        // executes before the window load event is fired.
    
        var docReady, onDocReady = function(){docReady = true;};
        if (document.readyState === undefined && document.addEventListener)
        {
            document.addEventListener("DOMContentLoaded", onDocReady, false);
            window.addEventListener("load", onDocReady, false);
        }
    
        window.loadBazaarvoiceApi = function(callback) {
            if (window.$BV) {
                callback();
            } else {
                getScript(bvapiUrl, function() {
                if (docReady) {
                    $BV.docReady();
                }
                callback();
                });
            }
        };
    })();
</script>

All subsequent calls to Bazaarvoice API functions, such as $BV.ui(), are wrapped in loadBazaarvoiceApi calls, as the following example shows:

loadBazaarvoiceApi(function() {
    $BV.ui("rr", "show_reviews", { productId: "test1" });
});

Implementing inline ratings

Including inline ratings on category or search pages provides useful summary information to consumers who are researching or comparing products. Inline ratings helps consumers select which products they want to view or which PDPs they want to drill down into.

Inline ratings code allows you to display:

  • Star rating images
  • Decimal value for the overall average rating (for example, 4.5)
  • Number of reviews (for example, 116)

You can implement inline ratings using two different methods:

Method comparison

Comparison Ratings & Reviews API Ratings-only export feed
Level of development effort Lower Higher
Statistics freshness Real-time updates Updated daily (potentially out-of-sync with stats on product page)
Local repository of statistics for use in other advanced areas such as faceted navigation or use in search results algorithms. No Yes
Format XML or JSON XML only

Method 1: Display inline ratings using Ratings & Reviews API (recommended approach)

Inline star ratings help your customers to research and compare products. The Ratings & Reviews API provides a highly optimized API method for retrieving review statistics such as average rating.

This method has been specifically built to handle high intensity applications such as search results pages and product category listing pages.

For example, you can call the Ratings & Reviews API for each desired product ID as a search results page is being rendered.

  • There is no need to cache these statistics locally prior to rendering the page.
  • There is no need to store a local copy of the star images. Bazaarvoice can host the star images.
  • This method gives you the flexibility to display the rating and images as you desire.
Note: Statistics returned by statistics.json/xml are global statistics calculated on the entire reviews set for a product across all locales. Contact Bazaarvoice Support if locale-specific statistics are required.
  1. To request production and staging keys for the Ratings & Reviews API, follow the Key Request Process .

  2. To request review statistics, use the appropriate product ID to call the Ratings & Reviews API:

  3. Map the overall ratings value (rounded to one decimal place) returned in the API response to link to the appropriate Bazaarvoice-hosted star image URL.

    • Image URL pattern:

      http://default.ugc.bazaarvoice.com/1235-en_us/[overall rating value]/[max rating:5]/rating.gif

      The following example retrieves the star image for 3.1 out of 5 stars:

      http://default.ugc.bazaarvoice.com/1235-en_us/3_1/5/rating.gif
  4. Use the API response and star image to display the inline rating image and overall rating value as needed on your category or search listing page.

Method 2: Display inline ratings using the ratings-only export XML feed

Inline star ratings help your customers to research and compare products. The ratings-only export feed is a daily XML-based export of product specific, ratings related content, including a series of star images. These star images represent rating values that range from 0.0 through 5.0 and are incremented by tenths.

  1. Store the images from the Bazaarvoice XML ZIP file on your server.
  2. Download the Bazaarvoice ratings-only export feed and perform one of the following steps:
    • Store the feed on your server for direct referencing for the rating and review count.
    • Insert the overall rating and review count into your database.
  3. Use the appropriate product ID to look up the following values in the static file or local database:
    • Overall ratings
    • Number of reviews
  4. Map the overall rating value in the database to the appropriate star image file. For example, if the overall rating value is 3.7, map it to the star image file named rating-3_7.gif.

For more information, refer to the ratings-only export feed topic.

Implement login redirection using JavaScript (site authentication)

Bazaarovice recommends implementing hosted authentication. However, if building the hosted implementation redirection logic is too costly or not technically feasible, follow these instructions to implement site authentication.

Note: Be aware that using site authentication might briefly present a blank page before redirecting consumers to the signin page. It may not provide the most optimal user experience.

  1. Place the following example code in the head section of every page where you want to display Bazaarvoice content:

    <script type="text/javascript" src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
</script>
<script type="text/javascript">
    $BV.configure("global", {
        userToken: "XXXXX",
        doLogin: function(successCallback, successUrl) {
            window.location = "http://www.client.com/login.html?return=" + encodeURIComponent(successUrl);
        }
    });
</script>

    XXXXX represents the Bazaarvoice encoded user authentication string (UAS). Refer to generating the user authentication string for more information. If an appropriate value is unavailable, leave this value blank.

  2. Replace the value of doLogin with the function that is called when Bazaarvoice requires user authentication.

After a successful login attempt on a separate page, the user is redirected back to the value of successUrl.

Integrate using AJAX-type login methods

successCallback can be executed if an AJAX-type login method is used and the user is still on the submission container page.

  1. Place the following example code in the head section on every page that you want to display Bazaarvoice content.

    <script type = "text/javascript"
src = "//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
    </script> <script type = "text/javascript">
    $BV.configure("global", {
        userToken: "XXXXX",
        doLogin: function(successCallback, successUrl) {
            myExampleAjaxLogin(function myExampleAfterLogin(encoded_user_string) {
                successCallback(encoded_user_string);
            });
        },
    }); 
</script>

    XXXXX represents the Bazaarvoice user authentication string (UAS). If an appropriate value is unavailable, leave this value blank.

  2. Replace the value of doLogin with the function that is called when Bazaarvoice requires user authentication.
  3. After the user successfully logs in to the system, call successCallback and pass the UAS as the first parameter.

Display content that resides behind a tab

If Bazaarvoice content is hidden behind a tab or other UI element, implement a callback so that the content can be displayed under the appropriate conditions, such as targeted links to a specific review or question or answer content.

To implement such a callback, define the doShowContent option in the appropriate show_* $BV.ui() call, as shown by the following example code.

<script type="text/javascript">
    $BV.ui("rr", "show_reviews", {
        productId: "XXXXX",
        doShowContent: function() { 
            myExampleShowTab("#ReviewsTab"); 
        }
    });
</script>

Although the preceding example code refers to a Ratings & Reviews integration, the doShowContent function applies to all feature integrations.

Bazaarvoice calls the function that is specified by doShowContent, so in the previous example, this function calls myExampleShowTab.

  • doShowContent supports asynchronous operations. A common need for such operations involves the inclusion of functions from popular JavaScript libraries, such as jQuery.
  • The function can be configured with callbacks to prevent the occurrence of actions that are based on content focusing. For example, returning a value of false from doShowContent prevents it from scrolling to content, as the following code shows.
function doShowContent(application, displayCode, subject, deepLinkId, callback, source ) {
    if ( I want to scroll ) {
        myExampleAsyncShowTab('#exampleReviewsTab', { onFinish: callback });
        return false;
    }
    else {
        return false;
    }
}

The following table identifies possible values for the source object. Use thes following values to prevent specific content-focusing actions, depending on the events that trigger them.

Value Content focusing is called by
readLink A Read XXXX link
deepLink A targeted URL
submission Returning from the submission flow

Implement same-page submission

Same-page submission allows you to use a single page for the display and submission of user-generated content.

The following topics describe the JavaScript functions that handle login duties, populate the submission iframe element, and manage the page display:

  • AJAX-type login method
  • Separate login page

Implement same-page submission with AJAX-type login methods

Although Bazaarvoice supports same-page submission, additional configuration options must be defined to account for all user interactions, including interactions that involve login integration.

Even if same-page submission is enabled, it’s recommended that you build a standalone submission container to drive the submission of UGC during email campaigns.

The following example code provides a stub of the code that must be implemented to support same-page submission with an AJAX-type login method.

<script type="text/javascript">
    $BV.configure("global", {
        allowSamePageSubmission: true,
        userToken: "XXXXX",
        doLogin: function(successCallback, successUrl) { 
            myExampleAjaxLogin(function myExampleAfterLogin(encoded_user_string) {
                successCallback(encoded_user_string); 
            });
        },
        doShowSubmission: function() {
            myExampleShowLightbox("Submission_Lighbox");
        },
        onSubmissionReturn: function() {
            myExampleCloseLightbox("Submission_Lighbox");
        },
        doScrollSubmission: function() {
            myExampleScrollToSubmission();
            return false;
        }
    });
</script>

Make the following changes to this code:

  1. Replace the userToken value of XXXXX with the Bazaarvoice encoded UAS. If you don’t have a value to place in this location, leave it blank.
  2. Replace the value of doLogin with a function of your design. Bazaarvoice calls this function when user authentication is required, provided the value of userToken is blank or not set.
  3. After a successful login attempt, call successCallback and pass the UAS as the first parameter.
  4. Replace the value of doShowSubmission with a function of your design. Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes or to switch to the tab into which the submission form must load.
  5. Replace the value of onSubmissionReturn with a function of your design. Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes or to switch away from the tab into which the submission form was loaded.
  6. Replace the value of doScrollSubmission with a function of your design. Bazaarvoice calls this function after the submission form is displayed or updated. This function can be used to prevent the default scrolling behavior by returning false.

  7. Place the following div element where you want the submission form to load on your product or category page.

    <div id="BVSubmissionContainer"></div>

    Alternatively, to load the submission form into a different div element, such as the div in which the main Bazaarvoice content loads, override the submission div name as shown by the following example for Ratings & Reviews.

    $BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

When this code is used in conjunction with the example $BV.configure, “Write a review” links cause the submission form to load in the location that displays the main block of reviews.

Note: $BV.configure calls must be made prior to any $BV.ui calls that they affect.

Implement same-page submission with a separate login page

You can enable same-page submission in conjunction with a separate login page (as opposed to an AJAX-type login method). The following example code provides a stub of the code that must be implemented.

<script type="text/javascript">
    $BV.configure("global", {
        allowSamePageSubmission: true,
        userToken: "XXXXX",
        doLogin: function(successCallback, successUrl) { 
            window.location = "http://www.client.com/login.html?return=" + encodeURIComponent(successUrl);
        },
        doShowSubmission: function() {
            myExampleShowLightbox("Submission_Lighbox");
        },
        onSubmissionReturn: function() {
            myExampleCloseLightbox("Submission_Lighbox");
        },
        doScrollSubmission: function() {
            myExampleScrollToSubmission();
            return false;
        }
    });
</script>

Make the following changes to this code:

  1. Replace the userToken value of XXXXX with the Bazaarvoice-encoded UAS. If you do not have a value to place in this location, leave it blank.
  2. Replace the value of doLogin with a function of your design. Bazaarvoice calls this function when user authentication is required. Ensure that the function redirects the user to the login form.
  3. After a successful login attempt on a separate page, redirect the user back to the value of successUrl.
  4. Replace the value of doShowSubmission with a function of your design. Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes or to switch to the tab into which the submission form must load.

  5. Replace the value of onSubmissionReturn with a function of your own design. Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes or to switch away from the tab into which the submission form was loaded.

    onSubmissionReturn is called only when the user is not redirected to the login page prior to submission. If the user is redirected, onSubmissionReturn is not called. Instead, the page is refreshed with the URL before the user is redirected to the login page. Define submissionReturnUrl to override this URL.

  6. Replace the value of doScrollSubmission with a function of your design. Bazaarvoice calls this function after the submission form is displayed/updated. This function can be used to prevent the default scrolling behavior by returning false.

  7. Place the following div element where you want the submission form to load on your product or category page.

    <div id="BVSubmissionContainer"></div>

    Alternatively, to load the submission form into a different div element, such as the div in which the main Bazaarvoice content loads, override the submission div name as shown by the following example for Ratings & Reviews.

    $BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

    When this code is used in conjunction with the example $BV.configure, “Write a review” links cause the submission form to load in the location that displays the main block of reviews.

Note: $BV.configure calls must be made prior to any $BV.ui calls that they affect.

Implement same-page submission (additional options)

Although Bazaarvoice supports same-page submission, additional configuration options must be defined to account for all user interactions.

Even if same-page submission is enabled, it’s recommended that you build a standalone submission container to drive the submission of user-generated content during email campaigns.

The following example code provides a stub of the code that must be implemented to support same-page submission.

<script type="text/javascript">
    $BV.configure("global", {
        allowSamePageSubmission: true,
        doShowSubmission: function() {
            myExampleShowLightbox("Submission_Lighbox");
        },
        onSubmissionReturn: function() {
            myExampleCloseLightbox("Submission_Lighbox");
        },
        doScrollSubmission: function() {
            myExampleScrollToSubmission();
            return false;
        }
    });
</script>

Make the following changes to this code:

  1. Replace the value of doShowSubmission with a function of your design. Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes or to switch to the tab into which the submission form must load.
  2. Replace the value of onSubmissionReturn with a function of your design. Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes or to switch away from the tab into which the submission form was loaded.
  3. Replace the value of doScrollSubmission with a function of your design. Bazaarvoice calls this function after the submission form is displayed/updated. This function can be used to prevent the default scrolling behavior by returning false.

  4. Place the following div element where you want the submission form to load on your product or category page.

    <div id="BVSubmissionContainer"></div>

    Alternatively, to load the submission form into a different div element, such as the div in which the main Bazaarvoice content loads, override the submission div name as shown by the following example for Ratings & Reviews.

    $BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

When this code is used in conjunction with the example $BV.configure, “Write a review” links cause the submission form to load in the location that displays the main block of reviews.

Note: $BV.configure calls must be made prior to any $BV.ui calls that they affect.

Track events using the JavaScript event callback

Use the JavaScript event callback to send detailed information about visitor interactions with Bazaarvoice user-generated content (UGC) to a single JavaScript function.

Using the event callback function, you can relay granular information about visitor interaction with UGC to your web analytics provider by simply choosing the information you want to capture from the event callback.

Common uses for the JavaScript event callback include:

  • Tracking the progress of a submission form and rates of abandonment.
  • Determining the average rating and review count of a product. This information helps establish a relationship between the rating or review count and the conversion rate of a product.
  • Dynamically generating portions of a page based on information that the hooks provide, such as the current phase of the submission process.

For additional guidance, refer to the following JavaScript event callback code examples.

Event callback example

To use the event callback, specify the onEvent option when making $BV API calls.

<script type="text/javascript">
    $BV.ui("rr", "show_reviews", {
        productId: "XXXXX",
        onEvent: function(json) { 
            if (json.eventSource == "Action") {
                myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
            }
        }
    });
</script>

Event variables for Ratings & Reviews

The following table identifies the specific variables that are associated with the attributes variable in Ratings & Reviews.

Variable Value Description
numReviews Integer Total number of approved reviews that are submitted on the product.
numRatingsOnlyReviews Integer Number of ratings-only reviews that are submitted on the product. By default, a ratings-only review contains fewer than 50 characters of review text and features no attached photos, videos, user entered tags, or additional user entered fields.
percentRecommend Integer (0-100) Percentage of users who selected Yes as an answer to the question "Would you recommend this product to a friend?"
avgRating Float Average rating of the product, expressed in a format that displays up to four decimal places.

Refer to the attributes parameter for more detailed information.

Ratings & Reviews example

<script type="text/javascript">
    $BV.ui("rr", "show_reviews", {
        productId: "XXXXX",
        onEvent: function(json) { 
            alert(json.attributes.numReviews);
        }
    });
</script>

Event variables for Questions & Answers

The following table identifies the specific variables that are associated with the attributes variable in Questions & Answers.

Variable Value Description
numQuestions Integer Total number of approved questions that are submitted about the subject.
numAnswers Integer Total number of approved answers that are submitted about the subject.

Questions & Answers example

<script type="text/javascript">
    $BV.ui("qa", "show_questions", {
        productId: "XXXXX",
        subjectType: "product",
        onEvent: function(json) { 
            alert(json.attributes.numQuestions);
        }
    });
</script>

Event variables for all Bazaarvoice products

The following table identifies the specific variables that are associated with the attributes variable in all Bazaarvoice products.

Variable Value Description
mediaType String Indicates that a visitor clicked hosted media within a piece of Bazaarvoice content. Possible values are photo and video.
filterType String

Indicates that a visitor clicked Filter By or Sort By and then selected a filter. Possible values are as follows:

  • Date – Newest First
  • Expert Reviews First
  • Photo Reviews First

Example

<script type="text/javascript">
    $BV.ui("qa", "show_questions", {
        productId: "XXXXX",
        subjectType: "product",
        onEvent: function(json) { 
            alert(json.attributes.mediaType);
        }
    });
</script>

Additional ‘analytics’ event variables

The following table identifies additional analytics variables that you can use.

Variable Values Description
attributes Specific to your Bazaarvoice feature or features Refer to the attributes parameter for more detailed information.
bvProduct RatingsAndReviews Current feature is Ratings & Reviews.
AskAndAnswer Current feature is Questions & Answers.
eType Read Content is available for the user to view.
Write User is engaged with the content-submission process.
Support User is engaged with additional submission processes, such as providing feedback or reporting content as inappropriate.
eventSource Display JavaScript Event API was invoked by injection.
Action JavaScript Event API was invoked by a user click or other action.
eventTarget Review Action is being performed on a review.
Question Action is being performed on a question.
Answer Action is being performed on an answer.
Comment Action is being performed on a comment.
Profile Action is being performed on a profile.
Story Action is being performed on a campaign item.
leafCategoryId Alphanumeric External ID of the category.
pageType (submission only) Input User is viewing the submission form.
Preview User is viewing the Preview page.
Confirm User is viewing the Thank You page or another end-result page.
pageStatus (submission only) Cancelled User cancelled the submission process.
AuthenticationFailure Valid UAS was not passed to Bazaarvoice.
Expired User's submission session expired.
AlreadySubmitted User attempted to submit duplicate content soon after the original submission.
Own User attempted to submit helpfulness feedback for own content.
Duplicate User attempted to submit helpfulness feedback for content for which they have already submitted feedback.
ValidationError User attempted to submit content that does not pass validation.
productId Alphanumeric External ID of the product.
rootCategoryId Alphanumeric External ID of the top-level category parent.

Contact Bazaarvoice Support to obtain a comprehensive list of analytics variables.

Event callback reporting parameters and values

The values passed into the parameters of the callback can be relayed to your web analytics provider:

  • The granularity of tracking depends on the parameters that you choose to relay to your web analytics provider.

  • The level of granularity that you can capture is highly flexible. You can combine values that are passed into the different parameters to track the types of interactions that occurred.

For example, you can pass a value to your web analytics provider to indicate that a visitor has read a review. Or you pass more granular information for the same interaction, such as the product ID, average rating, number of reviews, and interaction that triggered the read action.

The following types of parameters are associated with the event callback:

  • Parameters that are always passed to the JSON object of the JavaScript event callback.
  • Parameters that are sometimes passed to the JSON object of the JavaScript event callback (depends on the event that occurred).
  • Parameters that are associated with product related attributes - which are captured when an event with Bazaarvoice occurs.

eType (always passed)

The eType parameter answers the question “What general type of interaction occurred?” Use it to determine the overall type of event that occurred with Bazaarvoice content.

This parameter groups specific visitor interactions to provide an overview of visitors who are reading, contributing, or supporting content.

Value Description Example
Read Indicates the user consumed data without contributing UGC Reading, paginating, sorting, tag filtering, or expanding
Write Indicates the user engaged with any step of the content-submission process Writing a review, question, answer, or comment. Recommending a product
Support Indicates the user contributed supporting data Marking UGC as helpful or inappropriate, sharing content by using the social network buttons.
Note: Use the eType parameter in conjunction with the eName parameter to provide a more granular view of the specific read, write, or support action that occurred.

eventTarget (always passed)

Use the eventTarget parameter to identify the type of Bazaarvoice content visitors interacted with.

  • Example 1: If eType has a value of Write using Q&A, eventTarget identifies whether the visitor was in the process of writing a question or an answer.
  • Example 2: If eType has a value of Write using R&R, eventTarget identifies whether the visitor was in the process of writing a review or comment.

The eventTarget parameter can contain any value from the following table:

This value Indicates that a visitor... Under these conditions
Review Wrote or commented on a review, or submitted a vote that a review was helpful or inappropriate. bvProduct=RatingsAndReviews AND (eType=Write OR eType=Support)
Question Asked or commented on a question, or submitted a vote that a question was helpful or inappropriate. bvProduct=AskAndAnswer AND (eType=Write OR eType=Support)
Answer Wrote or commented on an answer, or submitted a vote that a question was helpful or inappropriate. bvProduct=AskAndAnswer AND (eType=Write OR eType=Support)
Comment Contributed a comment. All conditions
Profile Edited, commented on, or provided feedback for a user nickname. All conditions
Product Clicked Facebook Like functionality at the product level. All conditions
Gallery Clicked Bazaarvoice-hosted media. All conditions

eName (sometimes passed)

Use eName parameter answers the question “What specific type of event occurred?” with user-generated Bazaarvoice content. For example, did the user click, share, or sort content.

For example, if a visitor sorts reviews, this action is captured as a general read action with eType. However, the eName parameter indicates that the read action occurred as the result of the visitor sorting content.

Note: This parameter is most helpful when used in conjunction with the eType parameter to determine what type of read, write, or support action took place.

The eName parameter can contain any value from the following table:

This value Indicates that a visitor choose to... Under these conditions
Sort To sort Bazaarvoice content for a particular content type. eType=Read
AttributeFilter To use attribute filtering or Pros and Cons tags; loading content results from attribute filtering. eType=Read
WhiteSpace Something other than a link – such as whitespace, text, or an image – in a Bazaarvoice-hosted container. eType=Read OR eType=Write
ProductLink A product-recommendation link provided by another customer to view the product. eType=Read
ProductLink To add a product recommendation to a piece of content. eType=Write
Write "Write a(n) X" link to start the submission process. eType=Write
Associate To vote about the helpfulness of UCG, or to “Like (a product)” through Bazaarvoice. eType=Support
Inappropriate To submit a vote that a piece of UCG is inappropriate. eType=Support
ReadAll To read all of the content related to the "Read All X" link. eType=Read
ProductFollow A "Follow This Product" or "Follow New Reviews" link. eType=Read
Search To type a search query and click Search within a review or question. Type=Read
ProfileLink Clicked user-recommended product link. eType=Read
ProductLink Clicked a user recommended product. eType=Read OR eType=Write
QuestionSubmit Clicked Submit for a question on the Social Homepage. eType=Write
ResultsSelect Clicked a suggested question from the question submission form. eType=Read
SubmitActivity Clicked an element within the submission form. eType=Write

pageStatus (sometimes passed)

The pageStatus parameter is used to measure the number of visitors who received an error when attempting to submit Bazaarvoice content. It describes the error messages that are displayed to visitors. It answers the question “What type of error message did the visitor receive when attempting to submit content or feedback?”.

This metric helps to measure abandonment through the content-submission process by determining whether visitors encounter difficulties when writing content.

Note: Use this parameter in conjunction with bvProduct and eventTarget to identify the type of content that a visitor was attempting to submit when an error was received.

If present, pageStatus must contain one of the values in the following table:

This value Indicates this type of message Under these conditions
AuthenticationFailure Error message that appears when a visitor reaches a submission-container page without the appropriate encoding of the user authentication string (UAS) eType=Write OR eType=Support
Cancelled Confirmation message that appears after a visitor cancels the submission process eType=Write OR eType=Support
Expired Error message that appears when a visitor clicks Back after cancelling, effectively trying to resubmit the cancellation command for a submission that is already cancelled eType=Write OR eType=Support
AlreadySubmitted Error message that appears when a visitor attempts a duplicate submission soon after submitting the original content eType=Write OR eType=Support
Own Error message that appears when a visitor tries to submit a vote that their own content was helpful or inappropriate eType=Support
Duplicate Error message that appears when a visitor tries to resubmit feedback that a piece of UCG was helpful or inappropriate eType=Support
ValidationError A catch-all message for errors that are not otherwise identified eType=Write OR eType==Support

attributes (associated with product)

The attributes parameter answers the question “What are the Bazaarvoice-related attributes of the product that the visitor is viewing?”

Use the attributes parameter to measure values such as:

  • Average rating of a product
  • Number of reviews present when a product was viewed
Note: When this information is passed to your web analytics provider, you can report on the conversion rate of products with different ratings or varying numbers of reviews.

The attributes parameter can contain any value from the following table:

Bazaarvoice feature Variable Format Description
R&R numReviews Integer Total number of approved native reviews submitted for the product
numRatingsOnlyReIntegerviews Integer Number of ratings-only reviews submitted for the product. By default, a ratings-only review contains fewer than 50 characters of review text and features no attached photos, videos, visitor-entered tags, or additional visitor-entered fields
percentRecommend Integer (0-100) Percentage of visitors who selected Yes as an answer to the question "Would you recommend this product to a friend?". This question appears on a submission form
avgRating Float Average rating for the product. Expressed in a format that displays up to four decimal places
Q&A numQuestions Integer Total number of approved questions submitted about the product
numAnswers Integer Total number of approved answers submitted about the question
All Bazaarvoice products mediaType String Indicates that a visitor clicked hosted media within a piece of Bazaarvoice content. Possible values are photo and video
All Bazaarvoice products filterType String

Indicates that a visitor clicked Filter By or Sort By and then selected a filter. Possible values:

  • Date Newest First
  • Expert Reviews First
  • Photo Reviews First

Event callback code examples

Event callback generic example

To use the event callback, specify the onEvent option when making $BV API calls, as in the following example.

<script type = "text/javascript">
    $BV.ui("rr", "show_reviews", {
        productId: "XXXXX",
        onEvent: function(json) {
            if (json.eventSource == "Action") {
                myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
            }
        }
    }); 
</script>

Submission page actions

The following code runs when each page of the submission process loads, such as the Edit, Preview, or Submit page.

<script type="text/javascript">
    $BV.ui("submission_container", {
        onEvent: function(json) { 
            if ( json.eventSource == "Display" && (json.eType == "Write" || json.eType == "Support") ) {
                alert("Submission step: " + json.pageType);
            }
        }
    });
</script>

Ratings & Reviews user actions

The following code runs when a user clicks a link or performs an action in Ratings & Reviews.

<script type="text/javascript">
    $BV.ui("rr", "show_reviews", {
        onEvent: function(json) { 
            if ( json.eventSource == "Action" ) {
                alert("User click happened");
            }
        }
    });
</script>

Submission review length

The following code runs on your product pages to track the length of the review on the Bazaarvoice submission page.

< script type ="text/javascript" >
    $BV.ui("submission_container", {
        onEvent: function(json) {
            if (json.eventSource == "Display" && json.pageType == "Preview" && json.eventTarget == "Review") {
                myExampleAnalyticsTrackEvent("Bazaarvoice Review Length: " + json.submission¬ BodyLengthSummary + "^" + json.submissionBodyLength);
            }
        }
    }); 
</script>

Ratings & Reviews attributes

The following code runs on your product pages to track information about the Bazaarvoice review attributes for a product, such as the average rating, number of reviews, and percent of customers who recommend the product.

< script type ="text/javascript" >
    $BV.ui("rr", "show_reviews", {
            productId: "XXXXX",
            onEvent: function(json) {
                if (json.eventSource == "Display" &&
                    json.eType == "Read" && json.initialProductDisplay ==
                    "True") {
                    myExampleAnalyticsTrackEvent(json.attributes.avgRating);
                }
            }); 
</script>

In this example, XXXXX represents the ID of the product displayed on the page. This code runs only when a page that contains R&R content loads.

Questions & Answers attributes

The following is an example of the code that you place on your product pages to track information about the Bazaarvoice Q&A attributes for a roduct, such as the number of approved questions or approved answers for the product.

< script type ="text/javascript" >
    $BV.ui("qa", "show_questions", {
            productId: "XXXXX",
            subjectType: "product",
            onEvent: function(json) {
                if (json.eventSource == "Display" &&
                    json.eType == "Read") {
                    myExampleAnalyticsTrackEvent(json.attributes.numAnswers);
                }
            }); 
</script>

In this example, XXXXX represents the ID of the product that is displayed on the page. This code runs only when a page that contains Q&A content loads.