For Bazaarvoice Conversations to work, your website needs to communicate with the Bazaarvoice application. Your technical team should complete the steps in each section below.

Add code to product display pages

To display Ratings & Reviews or Questions & Answers content on product display pages (PDP), you must add Bazaarvoice code to the page’s HTML. The content that Bazaarvoice serves to your page takes advantage of Google's JavaScript indexing capabilities.

Caution: The following instructions are not compatible with the BV loader (bv.js); use these instructions if your implementation uses the scout file (bvapi.js). If your implementation uses bv.js, refer to the Display integration documentation.

Complete the following steps to integrate the essential Bazaarvoice code.

Step 1: Add the JavaScript API

To integrate the JavaScript API, complete the following steps on every page that will display Bazaarvoice content:

  1. Add the appropriate JavaScript code within the <head> tag.

    • Use the following code for the staging environment (The staging environment is for testing and development and is typically only visible internally. Ensure each Bazaarvoice URL referenced in the code contains "/bvstaging" in the domain).

      <script type="text/javascript" src="https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>
    • Use the following code for the production environment (The production environment is visible externally. Content in the production environment is visible on your live website).

      <script type="text/javascript" src="https://display.ugc.bazaarvoice.com/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>
  2. Replace <client_name> with the case-sensitive value provided by the Bazaarvoice implementation team.
  3. Replace <site_ID> with the ID of the deployment zone you want to use. This is set in the Bazaarvoice configuration hub within the Bazaarvoice Workbench. The default deployment zone is “main_site”. Check with your Bazaarvoice representative to ensure the correct name, or log in to the configuration hub to verify.
  4. Replace <locale> if the page does not use US English.

Be aware that bvapi.js cannot be loaded asynchronously. However, this file introduces no perceived performance impact in most conditions, and all remaining resources are loaded asynchronously.

Step 2: Insert the Bazaarvoice configuration call

Complete the following steps to call the Bazaarvoice configuration file:

  1. Insert the following JavaScript code in the <head> tag, after the bvapi.js call and before any $BV.ui calls.
    <script type="text/javascript"> 
        $BV.configure('global', { productId : 'ProductID123' });
    </script>
  2. Replace ProductID123 with the appropriate product ID. Product IDs are case sensitive. Avoid errors by ensuring the product ID exactly matches the corresponding ExternalId in your product catalog.

Step 3: Place the summary container

Insert the summary container (The summary container displays a summary of Ratings & Reviews or Questions & Answers data on the PDP. Bazaarvoice injects the latest data into <div id=”BVRRSummaryContainer”>, which is styled by your content display settings in the configuration hub) where you want the Ratings & Reviews or Questions & Answers summary to appear. Every product page must include the following summary container code.

<div id="BVRRSummaryContainer"></div>
Note: This code should only appear on the page once, even if you are implementing both Ratings & Reviews and Questions & Answers. Add this code near the top of your product page and near the product name or image as illustrated in the following image.

Step 4: Add Ratings & Reviews code

Insert the following code below the product description to display the Ratings & Reviews content.

Note: If this content will appear behind a tab or other conditionally visible UI element, Bazaarvoice will be unable to bring that content into view unless you provide the code to reveal it. You must use doShowContent to display the content, as shown in the following pseudo code.
<div id="BVRRContainer"></div>
<script type="text/javascript">
   $BV.ui( 'rr', 'show_reviews', {
      doShowContent : function () { 
         // If the container is hidden (such as behind a tab), put code here to make it visible 
         //(open the tab).
      }
   });
</script>

Step 5: Add Questions & Answers code

Insert the following code below the product description to display the Questions & Answers content.

Note: If this content will appear behind a tab or other conditionally visible UI element, Bazaarvoice will be unable to bring that content into view unless you provide the code to reveal it. You must use doShowContent to display the content, as shown in the following pseudo code.
<div id="BVQAContainer"></div>
<script type="text/javascript">
   $BV.ui( 'qa', 'show_questions', {
      doShowContent : function () { 
         // If the container is hidden (such as behind a tab), put code here to make it visible 
         //(open the tab).
      }
   });
</script>

Add schema.org markup

To make your reviews easier to crawl and index by search engines and to support rich snippets, like search results with star ratings, you must add schema.org markup to each product display page (PDP).

Why is schema.org markup important?

Customers often find products through search engines, so every PDP must communicate with search engines effectively. While enabling BVSEO will help search engines find your content, the major search engines look for schema.org markup when generating search results. Adding schema.org markup allows you to tag content search engines need to create rich snippets, which helps your content stand out on search results pages.

Note: You are responsible for completing the markup on each PDP.

The following table illustrates how schema.org markup enhances a search result snippet.

Without schema.org markup With schema.org markup
The standard snippet includes the item name, a short description, and a link. In addition to standard snippet information, this rich snippet includes the product star rating.

Add schema.org markup

Complete the following steps to add schema.org markup to a PDP.

  1. Add the following schema.org type code to your PDP code.
    <div itemscope itemtype="http://schema.org/Product">              

    The div must contain both BVRRSummaryContainer and BVRRContainer, as shown in the full code example. If you have implemented Questions & Answers, make sure you also include BVQAContainer.

    Note: Pages must only contain one schema.org type.
  2. Tag your product name with schema.org markup. Use one of the following lines of code, replacing ProductName with the product name used in your product feed.
    <!-- Add schema.org product class to the h1 tag-->
        <h1 itemprop="name">ProductName</h1> 
    <!-- Or add the class in meta tags-->     
        <meta itemprop="name" content="ProductName">          
    Note: Ensure that each product name is identical or very similar to the product name included in your product feed. Google requires similar product names across schema markup.

Full code example

The following example contains most of the code you must add to each PDP. Only use this code as a reference. Do not copy and paste this code without adding your company's specific information. You must modify this code to support your implementation and place each code snippet in the appropriate location in each page's HTML.

<!DOCTYPE html>
<html lang="en">
  <head>
      <!-- JavaScript API- Staging; replace in <client_name>, <site_ID>, and <locale>, and remove /bvstaging FOR PRODUCTION -->
      <script type="text/javascript" src="https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>

      <!-- Bazaarvoice Configuration Call -->
      <script type="text/javascript">
          $BV.configure('global', {
              productId: 'ProductID123' // Use relevant ExternalId from product feed
          });
      </script>
  </head>

  <body>
      <!-- schema.org Markup -->
      <div itemscope itemtype="https://schema.org/Product">  

          <h1 itemprop="name">ProductName</h1> <!--product name must be identified with itemprop=name attribute-->

          <!-- Summary Container goes above the fold near product name or image -->
          <div id="BVRRSummaryContainer"></div>

          <!-- Ratings & Reviews Container goes below product description -->
          <div id="BVRRContainer"></div>
          <script type="text/javascript">
              $BV.ui('rr', 'show_reviews', {
                  doShowContent: function() {
                    // If the container is hidden (such as behind a tab), put code here to make it visible 
                    //(open the tab).
                  }
              });
          </script>

          <!-- Q&A code -->
          <div id="BVQAContainer"></div>
          <script type="text/javascript">
              $BV.ui('qa', 'show_questions', {
                  doShowContent: function() {
                    // If the container is hidden (such as behind a tab), put code here to make it visible 
                    //(open the tab).
                  }
              });
          </script>
      </div>
  </body>
</html>               

Add review or question quantity to PDP pages

You can add code to customize a product display page (PDP) based on the number of product reviews or questions. Your code calls $BV.ui to return the total product review or question count and then executes an action based on that value.

To include the review count, use the following example code:

var rrPromise = $BV.ui('rr', 'show_reviews');
rrPromise.then(function (data) { 
  // Do something meaningful with the data
});

To include the question count, use the following example code:

var qaPromise = $BV.ui('qa', 'show_questions');
qaPromise.then(function (data) { 
  // Do something meaningful with the data
});

The data argument is an object with the following properties:

  • Id: The product identifier
  • TotalReviewCount: The total number of reviews for Id
  • TotalQuestionCount: The total number of questions for Id
  • TotalAnswerCount: The total number of answers for Id
  • TotalContentCount: The sum of TotalReviewCount, TotalQuestionCount, and TotalAnswerCount for Id

Integrate event callbacks

JavaScript event callbacks let your website respond to events that occur in the Bazaarvoice application, such as a consumer opening a review submission form. The Bazaarvoice application exposes a set of JavaScript events that you can use to respond to specific events. When a consumer triggers the event, the Bazaarvoice code executes the callback function you associated with the event, passing an object containing data about the event.

You can use JavaScript event callbacks to record and respond to customer interactions with the Bazaarvoice application. For example, you can:

  • Record when a consumer lands on a page rendering the Bazaarvoice application.
  • Record information about a consumer, such as name, phone number, and email address.
  • Measure the impact of certain events on key conversion metrics, such as the number of times consumers open but don’t submit the review submission form.
  • Display content in response to a consumer’s interaction with the Bazaarvoice application, such as displaying a coupon after the consumer completes a review.

Complete the following steps to integrate JavaScript event callbacks:

  1. Select an event you want to watch.

    When you specify a callback for an event, the callback function executes when the event occurs. You can specify a callback for the following events:

    • bvRender—Triggered when the application initially renders on the site.
    • submissionLoad—Triggered when a consumer opens a submission form for such activities as writing a review, leaving a comment, or answering a question.
    • submissionClose—Triggered when a consumer closes a submission form without submitting it.
    • submissionSubmitted—Triggered when a consumer submits a submission form.

    When you specify a callback function for one of these events, the function can receive an object as its sole argument. This object contains information about the event. You can select from the following object properties:

    • Id—Product ID
    • TotalAnswerCount—Number of answers for the product
    • TotalQuestionCount—Number of questions for the product
    • TotalReviewCount—Number of reviews for the product
    • TotalContentCount—Total number of content items for the product, if relevant

    In addition to the above properties, the submissionLoad, submissionClose, and submissionSubmitted events receive an object with a contentType property, which indicates the type of content associated with the submission. Possible type values include Review, Comment, Question, and Answer.

  2. Add a callback function to $BV.configure global configuration.

    Locate the $BV.configure call in your code, and add the event callback with the JavaScript code you want to execute when the event occurs.

    The following code associates a callback function with the bvRender event.

    <script>
    $BV.configure('global', {
      events : {
        bvRender : function (data) {
          // JavaScript code that executes when the Bazaarvoice application renders.
        }
      }
    });
    </script>

Performance and load time

Bazaarvoice content should not slow down your site because the majority of Bazaarvoice files are non-blocking or asychronous. The scout file (bvapi.js) is the only synchronous Bazaarvoice code on your page. It loads at the same time as the rest of the content on the page. The locations of the scout file and the $BV.ui call affect the load time of the asynchronous content because the content will not load until the scout file has loaded.

Complete the following steps to optimize load time:

  1. Place the scout file (bvapi.js) inside the <head> tag of the page as high as possible, ideally right after the core site components.
  2. Place the $BV.ui call in the <body> tag as high as possible.
  3. Perform speed tests on your site to ensure your Bazaarvoice content is loading as efficiently as possible.

Perform a speed test

To analyze how Bazaarvoice integrates with your site, use WebPagetest to run the following performance tests. Run each test in a new tab so you can review them side by side. You can use any configuration settings as long as they remain consistent for all tests. After testing, compare the results to more easily determine what might be slowing your site down.

  1. Test Bazaarvoice in isolation. Bazaarvoice provides a hosted container page to load your configured Conversations implementation. Paste the following URL into the Enter a Website URL field on the WebPagetest home page, replacing the following variables with your values.
    http://display.ugc.bazaarvoice.com/common/util/clientTestPage.html?client=<client_name>&site=<site_name>&locale=<locale>&productId=<product_ID>

    where

    • <client_name>—The client name you use to log into the workbench. This value is case sensitive.
    • <site_name>—The deployment zone. For example, Main Site would be written as main_site. The site name can also be found in the deployment zone of the configuration hub under Site ID.
    • <locale>—The locale used by the implementation. For example, en_US for English. The locale is case sensitive.
    • <product_ID>—The product ID (external ID) listed in the product feed for the product whose Bazaarvoice content you want to use in the test.
  2. Test your hosted product page with Conversations implemented by entering the URL of the page in the Enter a Website URL field. Choose a product page that will consistently load the same content for the most accurate test results.
  3. Test your hosted product page with Conversations blocked. Expand the Advanced Settings options on the WebPagetest home page. In the Block tab, enter bvapi in the Block Requests Containing field. Start the test using the same URL from step 2. Blocking the request to bvapi.js will prevent further requests to Bazaarvoice and provide you with a load time for your page without Bazaarvoice content.

Note: Test results can change dramatically even in a consistent testing environment due to machine and network fluctuations.

Review the speed test

The key metrics to review are in the WebPagetest Summary and Details tabs. Depending on what Bazaarvoice applications you are loading on the page you tested, the names of these containers may differ slightly. For the following review steps, the key metrics are based off a page hosting Conversations Ratings & Reviews.

Note: These metrics may not match those in your tests.

Review Conversations in isolation

To get the render time from this first test, go to the Details tab and subtract the value of scoutStart from the value of reviewContentList1-render-end. The result is the time it took to initiate the bvapi.js scout file and load Ratings & Reviews on the page.

Review your hosted product page with Conversations implemented

Gather the following metrics from the Details tab:

  • The time bvapi.js was requested (found in the Request Details section)
  • The time of the rr_show_reviews-call performance mark
  • The time of the reviewContentList1-render-end performance mark

Refer to the previous metrics for the following measures:

  • If the time to request bvapi.js is greater than 1000ms, move the $BV.ui call higher up the page.
  • If the difference in time to request rr_show_reviews-call and bvapi.js is greater than 500ms, Conversations is on the page but has not yet been told to render. Move the $BV.ui call immediately after the reference to bvapi.js.
  • If the difference in time to request reviewContentList1-render-end and rr_show_reviews-call is greater than three seconds and performance issues arise when you review your hosted product page with Conversations blocked, Bazaarvoice code may be competing for network bandwidth and processing power in the web browser. Contact your Bazaarvoice representative for support.

Review your hosted product page with Conversations blocked

If the metrics for Document Complete or Fully Loaded are greater than 3000ms when running the test with bvapi blocked, your page is probably attempting to load too much content on startup. If Start Render is greater than 1000ms, that is also an indicator of too much content attempting to load on startup. Contact your Bazaarvoice representative for support.

If no performance issues occurred when testing your product page with Conversations blocked, but there were issues with the page with Conversations enabled, a conflict between your code and Bazaarvoice code may exist. Contact your Bazaarvoice representative for support.

Common performance issues

The following conditions are common causes for slow load times.

Too much JavaScript

Pay attention to the execution times of JavaScript, third party or otherwise, being loaded on your page. A script that appears to have excessive execution times could be adding unnecessary overhead to your page's overall load time.

Too many JavaScript files

If the number of requests for JavaScript files is disproportionately high, your page may be encountering extra network congestion to get that content. If you're seeing 20 or more requests for .js files from the same domain, consider concatenating those files.

Not using Content Delivery Networks (CDNs) or caching effectively

The Performance Review tab contains metrics about your use of CDNs and caching. If your page is content rich with no caching, this can impact the load time of first visits and repeat visits.

Too many images

If your page is filled with images, ensure you are optimizing and compressing those images and dynamically loading additional images for carousels or galleries after initial page render.

Add this code where you want to display the Bazaarvoice content on your pages:

<!DOCTYPE html>
<html lang="en">
  <head>
      <!-- JavaScript API- Staging; replace in <client_name>, <site_ID>, and <locale>, and remove /bvstaging FOR PRODUCTION -->
      <script type="text/javascript" src="https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>

      <!-- Bazaarvoice Configuration Call -->
      <script type="text/javascript">
          $BV.configure('global', {
              productId: 'ProductID123' // Use relevant ExternalId from product feed
          });
      </script>
  </head>

  <body>
      <!-- schema.org Markup -->
      <div itemscope itemtype="https://schema.org/Product">  

          <h1 itemprop="name">ProductName</h1> <!--product name must be identified with itemprop=name attribute-->

          <!-- Summary Container goes above the fold near product name or image -->
          <div id="BVRRSummaryContainer"></div>

          <!-- Ratings & Reviews Container goes below product description -->
          <div id="BVRRContainer"></div>
          <script type="text/javascript">
              $BV.ui('rr', 'show_reviews', {
                  doShowContent: function() {
                    // If the container is hidden (such as behind a tab), put code here to make it visible 
                    //(open the tab).
                  }
              });
          </script>

          <!-- Q&A code -->
          <div id="BVQAContainer"></div>
          <script type="text/javascript">
              $BV.ui('qa', 'show_questions', {
                  doShowContent: function() {
                    // If the container is hidden (such as behind a tab), put code here to make it visible 
                    //(open the tab).
                  }
              });
          </script>
      </div>
  </body>
</html>               

Verify the following: