Loading the API asynchronously

All Bazaarvoice content except the API loader file bvapi.js is loaded asynchronously. If you must load this content asynchronously as well, do not include the bvapi.js script tag directly on your HTML pages. Instead, include one of the following script blocks, depending on whether you use jQuery:

  • 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

Bazaarvoice recommends adding the following elements to pages that display multiple products in a list or grid, such as category and search-results pages:

  • The product’s overall rating
  • A star image that represents the overall rating
  • The number of reviews

Bazaarvoice provides two methods by which inline ratings can be implemented:

  • Ratings XML feed
  • Platform API (recommended approach)

Method comparison

 Platform APIRatings XML Data Feed
Level of development effortLowerHigher
Statistics freshnessReal-time updatesUpdated only daily (potentially out-of-sync with stats on product page)
Local repository of statistics for use in other advanced areas (e.g., faceted navigation, use in search results algorithms, etc.)NoYes
FormatXML or JSONXML only

The Conversations 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, the Conversations API can be called for each desired product ID as a search results page is being rendered. There is no requirement to cache these statistics locally prior to rendering the page. Additionally, Bazaarvoice can host the star images for use in the application. There is no need to store a local copy of 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. If locale-specific statistics are required, contact your Implementation Engineer.
  1. Follow the Key Request Process to get production and staging keys for the Conversations API.
  2. Use the appropriate product ID to call the Conversations API to request review statistics:
  3. Map the overall ratings value (rounded to one decimal place) returned in the API response to link to the appropriate BV-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. Utilize 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.

Using ratings XML feed for inline ratings

Bazaarvoice provides a ZIP file that contains a series of star image files. These images represent ratings values that range from 0.0 through 5.0 and are incremented by tenths.

  1. Store the images from the Bazaarvoice ZIP file on your webserver.
  2. Download the Bazaarvoice ratings-only export feed and perform one of the following steps:
    • Store the feed on the webserver for direct referencing of the rating and review count.
    • Insert the overall rating and review count into your webstore 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 about ratings-only export feed, refer to Bazaarvoice Data Feeds.

Implementing login redirection with JavaScript

A client-side JavaScript option for login redirection can be implemented if the process of building the redirection logic on the server side is too costly or not technically feasible. However, a client-side solution might briefly present users with a blank page before redirecting them to the Login page. As a result, this solution might not provide the most optimal user experience.

  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) { 
                window.location = "http://www.client.com/login.html?return=" + encodeURIComponent(successUrl);
            }
        });
    </script>
    

    where XXXXX represents the Bazaarvoice-encoded UAS. For more information, see “Generating the User Authentication String.” 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. The code in step 1 provides an example of redirecting to a login page that features a defined return URL.

Integrating with 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>
    

    where the XXXXX represents the Bazaarvoice-encoded 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.

Displaying content that resides behind a tab

If Bazaarvoice content is hidden behind a tab or other conditionally visible UI element, implement a callback so that the content can be displayed under the appropriate conditions, such as targeted links to a specific review, question, answer, or campaign 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 pertains to a ratings and reviews integration, the manner in which doShowContent specifies a function applies to all feature integrations.

When the primary content container needs to be visible, Bazaarvoice calls the function that is specified by doShowContent. 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. Additionally, 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.

If the value is...Content focusing is called by...
readLinkA Read XXXX link
deepLinkA targeted URL
submissionReturning from the submission flow

Use these values to prevent specific content-focusing actions, depending on the events that trigger them.

Use targeted URLs to link directly to a specific review, question, answer, campaign, or other piece of content. These URLs redirect to the applicable product or category page while setting a cookie that instructs the Bazaarvoice integration on that page to display the appropriate content at the top of the main Bazaarvoice display area.

Ensure that the following prerequisites are satisfied before implementing this feature:

  • If the primary Bazaarvoice content resides behind a tab or depends on JavaScript running before it can be made visible, define a JavaScript function for the doShowContent option. Otherwise, Bazaarvoice cannot automatically open the tab that contains the targeted content.
  • The product feed must contain a valid product or category page URL for the corresponding product or category ID in the targeted link. This URL allows Bazaarvoice to redirect users to the appropriate product or category page. If a valid URL is not defined, you can specify a value explicitly as a parameter in the targeted link.

Example formats: Targeted URLs

The sections in this topic provide examples of targeted URLs. Regardless of the URL format that you use, ensure that /bvstaging is removed from the URLs in your production environment.

Reviews

The following URL shows the format of a URL that deep links to a review.

http://reviews.client.com/bvstaging/1235-en_us/XXXXX/review/YYYYY/redirect.htm

In this example, XXXXX represents the product ID, and YYYYY represents the review ID.

Review comments

The following URL shows the format of a URL that deep links to a review comment.

http://reviews.client.com/bvstaging/1235-en_us/XXXXX/review/YYYYY/comment/ZZZZZ/redirect.htm

In this example, XXXXX represents the product ID, YYYYY represents the review ID, and ZZZZZ represents the review comment ID.

Questions

The following URLs show the format of a URL that deep links to a question:

  • http://answers.client.com/bvstaging/answers/1235-en_us/product/XXXXX/question/YYYYY/redirect.htm
  • http://answers.client.com/bvstaging/answers/1235-en_us/category/XXXXX/question/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the question ID.

Answers

The following URLs show the format of a URL that deep links to an answer:

  • http://answers.client.com/bvstaging/answers/1235-en_us/product/XXXXX/answer/YYYYY/redirect.htm
  • http://answers.client.com/bvstaging/answers/1235-en_us/category/XXXXX/answer/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the answer ID.

Campaigns

The following URLs show the format of a URL that deep links to campaign content:

  • http://Default/bvstaging/stories/1235-en_us/product/XXXXX/story/YYYYY/redirect.htm
  • http://Default/bvstaging/stories/1235-en_us/category/XXXXX/story/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the campaign content ID.

Campaign comments

The following URLs show the format of a URL that deep links to a comment on a piece of campaign content:

  • http://Default/bvstaging/stories/1235-en_us/product/XXXXX/story/YYYYY/comment/ZZZZZ/redirect.htm
  • http://Default/bvstaging/stories/1235-en_us/category/XXXXX/story/YYYYY/comment/ZZZZZ/redirect.htm

In these examples, XXXXX represents the product or category ID, YYYYY represents the campaign content ID, and ZZZZZ represents the comment ID.

Overriding redirect URLs

If the URL that corresponds to the product or category page is not sent to Bazaarvoice or if an alternate URL is desired, you can add the redirecturl parameter to explicitly define the URL to which Bazaarvoice redirects. If you add the redirecturl parameter, the base domain of the redirect URL must match the base domain of the targeted URL for security reasons.

The following URL provides an example override:

http://reviews.client.com/bvstaging/1235-en_us/pid123/review/4567/redirect.htm?redirecturl=http%3A%2F%2Fwww.client.com%2Fpid123.html

Ensure that /bvstaging is removed from the URL before launching in your production environment.

Sharing content through Facebook

Implement Facebook sharing to allow your customers to bookmark content that they want to share with their social networks.

Updating Facebook tags

Update your Facebook tags if you are implementing either the Facebook Like.

Facebook Like

Define the Facebook namespace if you have enabled either of the following options:

  • The Facebook Like button integration
  • Publishing to Facebook from the submission page

If one of these options is enabled but the Facebook namespace is not defined, Internet Explorer might behave in an unreliable manner. Declare the fb namespace within the opening html element, as the following example shows.

<html xmlns:fb="http://www.facebook.com/2008/fbml">

If other namespaces or attributes are already defined within the opening html element, leave them intact.

Social Buttons

Social buttons allows your customers to bookmark content that they want to share with their social networks. Bookmarks appear in the Bazaarvoice-supported locations of your choice, as the following image shows.

When you share content with Facebook, the social-networking site’s bots crawl your pages and search for titles, descriptions, thumbnail images, and other information. Although the bots might estimate some of the values that Facebook uses, you can use the following metadata tags to specify exact values:

<meta property="og:title" content="XXXXX" />

where XXXXX represents the title of the page.

<meta property="og:description" content="YYYYY" />

where YYYYY represents the description of the page.

<meta property="og:image" content="ZZZZZ" />

where ZZZZZ represents the URL that points to the image you want Facebook to use as the thumbnail.

For additional information, visit http://developers.facebook.com/docs/share.

Creating an application for Facebook

Bazaarvoice lets your customers publish submissions directly to their Facebook walls. To take advantage of this feature, you must either create a new Facebook application (app) for Bazaarvoice to utilize or provide us with access to an appropriate app that you already use.

Bazaarvoice requires the following information for the Facebook app that you plan to use:

  • AppID
  • API key
  • App secret, which is stored as an encrypted value

Additionally, the Facebook app must be configured to match the domain on which the submissions occur. Note that if your staging environment (or any other non-production environment you wish to test against) has a different domain than your production environment, you’ll need to configure separate a Facebook app for each domain.

The following topics describe the process of creating a new Facebook app and help you identify the information that Bazaarvoice requires for you to use an existing app.

Creating a new Facebook application

  1. Use a standard Web browser and the administrator-level credentials that are associated with your Facebook account to access http://www.facebook.com/developers. The Developer page opens.
  2. Click Set Up New App in the upper-right corner. The Essential Information page opens.
  3. Perform the following steps:
    1. In the App Name text box, specify an app name that is relevant to your brand and meaningful to your customers.
    2. Click Agree to indicate that you agree to the Facebook terms and conditions.
    3. Click Create App.
    4. (Optional) If you are asked to complete a CAPTCHA, specify the appropriate information and click Submit.

    The About page opens.

  4. Upload a logo for Facebook to use.
  5. In the navigation panel, click Web Site. The Web Site page opens.
  6. Perform the following steps on the Web Site page:
    1. In the Site URL text box, specify the appropriate URL, which is typically your homepage, in the following format:

      http://www.client.com

    2. In the Site Domain text box, specify the appropriate domain in the following format:

      client.com

    3. Click Save Changes.

      The Summary page opens, displaying the application settings and any relevant usage statistics.

  7. Send the values that correspond to the app ID, API key, and app secret to your Bazaarvoice engineer.

Using an existing Facebook application

  1. Use a standard Web browser and the administrator-level credentials that are associated with your Facebook account to access http://www.facebook.com/developers. Your existing Facebook apps are displayed on the Developer page.
  2. Click the name of the appropriate app. The app ID, API key, and app secret are displayed.
  3. Send the values that correspond to the app ID, API key, and app secret to your Bazaarvoice engineer.
  4. Confirm that the site URL corresponds to your homepage and that the site domain corresponds to the domain on which Bazaarvoice submissions will occur. If these values are set to other domains or URLs, you might want to create a new application for Bazaarvoice to use.
  5. (Optional) To change these values, click Edit Settings and then click Web Site in the navigation panel.

Same-page submission

Same-page submission allows you to use a single page for both the display and submission of UGC.

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

Same-page submission allows you to use a single page for both the display and submission of UGC. The following topic describes the JavaScript functions that populate the submission iframe element and manage the page display.

Example code is provided.

Implementing 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 is 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 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, 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/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 and 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.

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

Implementing same-page submission with a separate login page

To enable same-page submission but use it 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 whenever 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 and 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.

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

Implementing same-page submission

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 is 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.

<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 and 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.

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

Implementing ratings and reviews on your mobile site

The mobile-optimized version of ratings and reviews is integrated with your existing mobile site. Visitors who access your site by way of their JavaScript-enabled mobile devices can find it easier to view and contribute content.

If your business decides to render the mobile-optimized version of ratings and reviews, perform the following steps to implement this feature:

  1. Contact the Bazaarvoice Support team to start the implementation process.
  2. Add the displayType configuration option to the global scope and set it to mobile, as the following example code shows.

    $BV.configure("global", {
        ...
        displayType: "mobile",
        ...
    });
    

    Ensure that you add the displayType configuration option only to the display and submission pages that you want to render as the mobile-optimized version of ratings and reviews. Do not set this option to mobile for every display and submission page, as the non-mobile-optimized version of ratings and reviews must be able to render on your non-mobile site.

  3. You can use simple submission URLs to direct users to the mobile version of the review submission form. To do so, set format query string parameter to a value of “mobilestandalone”. Example:

    http://reviews.client.com/1235-en_us/productXYZ/writereview.htm?return=http%3A%2F%2Fwww.client.com%2FproductXYZ.html&format=mobilestandalone

Using the event callback

The Bazaarvoice JavaScript event callback enables you to track certain actions that occur with Bazaarvoice UI components. For example, the event callback can be used to pass tracking information into your web analytics system.

Common uses for the JavaScript event callback include the following examples:

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

Example: Event callback

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

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

VariableValueDescription
numReviewsIntegerTotal number of approved reviews that are submitted on the product.
numRatingsOnlyReviewsIntegerNumber 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.
percentRecommendInteger (0-100)Percentage of users who selected Yes as an answer to the question "Would you recommend this product to a friend?"
avgRatingFloatAverage rating of the product, expressed in a format that displays up to four decimal places.

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.

VariableValueDescription
numQuestionsIntegerTotal number of approved questions that are submitted about the subject.
numAnswersIntegerTotal number of approved answers that are submitted about the subject.

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 Campaigns

In campaigns, the numStories variable is specifically associated with the attributes variable and identifies the total number of approved campaign submissions for the corresponding product. The value of numStories can be any integer.

Example

<script type="text/javascript">
    $BV.ui("sy", "show_stories", {
        productId: "XXXXX",
        subjectType: "product",
        onEvent: function(json) { 
            alert(json.attributes.numStories);
        }
    });
</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.

VariableValueDescription
mediaTypeStringIndicates that a visitor clicked hosted media within a piece of Bazaarvoice content. Possible values are photo and video.
filterTypeString

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

Update for current topic.

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

Additional event variables

The following table identifies some of the additional web analytics variables that pertain to common scenarios.

VariableValuesDescription
attributesSpecific to your Bazaarvoice feature or featuresSee previous sections.
bvProductRatingsAndReviewsCurrent feature is ratings and reviews.
AskAndAnswerCurrent feature is question and answer.
StoriesCurrent feature is campaigns.
ProfilesCurrent feature is profiles.
eTypeReadContent is available for the user to view.
WriteUser is engaged with the content-submission process.
SupportUser is engaged with additional submission processes, such as providing feedback or reporting content as inappropriate.
eventSourceDisplayJavaScript Event API was invoked by injection.
ActionJavaScript Event API was invoked by a user click or other action.
eventTargetReviewAction is being performed on a review.
QuestionAction is being performed on a question.
AnswerAction is being performed on an answer.
CommentAction is being performed on a comment.
ProfileAction is being performed on a profile.
StoryAction is being performed on a campaign item.
leafCategoryIdAlphanumericExternal ID of the category.
pageType (submission only)InputUser is viewing the submission form.
PreviewUser is viewing the Preview page.
ConfirmUser is viewing the Thank You page or another end-result page.
pageStatus (submission only)CancelledUser cancelled the submission process.
AuthenticationFailureValid UAS was not passed to Bazaarvoice.
ExpiredUser's submission session expired.
AlreadySubmittedUser attempted to submit duplicate content soon after the original submission.
OwnUser attempted to submit helpfulness feedback for own content.
DuplicateUser attempted to submit helpfulness feedback for content for which he or she has already submitted feedback.
ValidationErrorUser attempted to submit content that does not pass validation.
productIdAlphanumericExternal ID of the product.
rootCategoryIdAlphanumericExternal ID of the top-level category parent.
VariableValuesDescription
attributesSpecific to your Bazaarvoice product or productsSee previous sections.
bvProductRatingsAndReviewsCurrent product is ratings and reviews.
AskAndAnswerCurrent product is question and answer.
StoriesCurrent product is campaigns.
ProfilesCurrent product is profiles.
eTypeReadContent is available for the user to view.
WriteUser is engaged with the content-submission process.
SupportUser is engaged with additional submission processes, such as providing feedback or reporting content as inappropriate.
eventSourceDisplayJavaScript Event API was invoked by injection.
ActionJavaScript Event API was invoked by a user click or other action.
eventTargetReviewAction is being performed on a review.
QuestionAction is being performed on a question.
AnswerAction is being performed on an answer.
CommentAction is being performed on a comment.
ProfileAction is being performed on a profile.
StoryAction is being performed on a campaign item.
leafCategoryIdAlphanumericExternal ID of the category.
pageType (submission only)InputUser is viewing the submission form.
PreviewUser is viewing the Preview page.
ConfirmUser is viewing the Thank You page or another end-result page.
pageStatus (submission only)CancelledUser cancelled the submission process.
ExpiredUser's submission session expired.
AlreadySubmittedUser attempted to submit duplicate content soon after the original submission.
OwnUser attempted to submit helpfulness feedback for own content.
DuplicateUser attempted to submit helpfulness feedback for content for which he or she has already submitted feedback.
ValidationErrorUser attempted to submit content that does not pass validation.
productIdAlphanumericExternal ID of the product.
rootCategoryIdAlphanumericExternal ID of the top-level category parent.

Contact your IPM to obtain a comprehensive list of web analytics variables.

Examples

The following code runs whenever 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>

The following code runs whenever a user clicks a link or performs another 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>