The following topics contain instructions for how to inject Bazaarvoice UGC on your site based on the features you plan to implement.

The integration code in this section contains the path /bvstaging in its example URLs. This token routes requests to the Bazaarvoice staging environment. It is recommended that you design your implementation of the Bazaarvoice integration code in a manner that allows you to toggle easily between including or excluding the path /bvstaging in or from the appropriate URLs. Ensure that /bvstaging is removed from the URLs in your production environment.

Loading ratings and reviews content

To load ratings and reviews on a product display page (PDP), you can add a summary container and reviews container to the PDP. The summary container is typically placed at the top of the page and provides an overview of the ratings. The reviews container is the primary display area for all ratings and reviews submitted for the product.

For the summary container, you have two options: primary ratings summary and rating summary (“fast stars”). Here are the differences:

 Primary rating summaryRating summary ("fast stars")
What is displayed?
  • Five-icon image indicating the average product rating (icon is customizable)
  • Total number of reviews for the product
  • Number of customers who would recommend to a friend
  • Interactive histogram that provides a rating breakdown
  • Number of questions and answers for the product
  • "Write a review," "Read X reviews," and "Ask a question" links
  • Links to share to social networking sites
  • Five-star image indicating the average product rating
  • Total number of reviews for the product
  • Percent (%) of customers who recommend the product
  • Interactive histogram that provides a rating breakdown and filtering
  • Number of questions and answers for the product
  • "Write a review," "Read X reviews," and "Ask a question" links
Integration scriptbvapi.jsbv.js
AdvantagesCan be customized extensively.
  • Much smaller file size and renders much faster.
  • Less integration code to implement.
  • Supports upcoming performance improvements and innovations.
Limitations
  • Larger file size and renders much slower.
  • More integration code to implement.
  • Site authentication is not supported.
  • Iframe integration not supported.
  • Special implementation code is not supported, such as $BV.getConfiguration.
  • Custom stars and other icons are not supported.
  • Campaigns and category IDs are not supported.
InstructionsPrimary ratings summary and reviews containersRating summary (fast stars), reviews, and questions containers
Note: Bazaarvoice encourages you to implement the BV loader file (bv.js) and the <div> tags documented below for performance improvements and future innovations. If you choose to use bv.js and these instructions for display integration, you must contact Bazaarvoice Client Care to enable the rating summary ("fast stars") feature. The code for this feature will not work if Support does not enable them.

Primary ratings summary and reviews containers

  1. Place the following code within the head element.

    <script type="text/javascript" 
        src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
    </script>
    <script type="text/javascript">
        $BV.configure("global", {
            submissionContainerUrl: "http://www.client.com/submissionPage.html"
        });
    </script>
    

    Where:

    • submissionContainerUrl is the URL for the submission container page.
    • /bvstaging is removed from the URL before launching in your production environment.
    • $BV.configure calls are executed prior to any $BV.ui calls that they affect.
    • bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the “Loading the API Asynchronously” section for additional information. Asynchronous content loading is not common.
    Note:  For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain links are clicked. This warning page is normal for development and staging purposes and is common if you are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.

    After you confirm that the URL presented on the warning page is the URL that you want to use for development, it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.
  2. Place the following div element on every product page where you want to display the primary ratings summary:

    <div id="BVRRSummaryContainer"></div>
    
  3. Place the following div element on every product page where you want to display the actual reviews:

    <div id="BVRRContainer"></div>
    
  4. Make the following $BV.ui() call to load content into the div elements that you inserted during the previous step:

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

    where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that is associated with the product in the data feed. We recommend that you place this code in the head element.

Rating summary (fast stars), reviews, and questions containers

This section provides the following instructions:

  • Adding code to your pages to display the new rating summary (fast stars), reviews, and questions containers
  • Adding custom code to show content that is hidden, such as behind a tab
  • Removing old integration code if you are implementing the new containers that are supported by the BV loader framework

Troubleshooting information is also provided at the end of this section.

Add integration code for the containers

  1. Place the following code within the head element.

    <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/<environment>/<locale>/bv.js"></script>
    

    Where:

    • async—Downloads the BV loader asynchronously. This attribute is optional but recommended.
    • src—Specifies the path to the BV loader. Replace the following elements in your HTML:
      • <client_name>— The client name provided by Bazaarvoice. Be sure to use lowercase letters for the value.
      • <site_ID>—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 ID, or click to the right of the deployment zone on the Site Manager page of the configuration hub.
      • <environment>—The deployment environment where you want to implement Bazaarvoice features. For a production environment, include production in the path. If you are referencing a staging environment, include staging in the path.
      • <locale>—The locale that is used by the implementation. For example, en_US for English.
    Note:  For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain links are clicked. This warning page is normal for development and staging purposes and is common if you are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.

    After you confirm that the URL presented on the warning page is the URL that you want to use for development, it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.
  2. Position the rating summary as close to the product name and image as possible in the body element. Here is the required HTML code for this feature:

    <div data-bv-show="rating_summary" data-bv-productId="ExternalId"></div>
    

    The data-bv-show data attribute instructs the BV loader to display the rating summary, and data-bv-productId instructs the BV loader to display the feature for a specified product ID, which must match the ExternalId provided in the product catalog.

    If you want to display multiple rating summaries on a PDP, add the data-bv-seo=”false” data attribute to subsequent rating summary <div> tags. This ensures that schema.org metadata is rendered for the first rating summary only. If schema.org metadata is rendered for more than one rating summary on a page, it interferes with the page’s SEO. Here is an example:

    <div data-bv-show="rating_summary" data-bv-productId="ExternalId-1"></div>
    ...
    <div data-bv-show="rating_summary" data-bv-productId="ExternalId-2" data-bv-seo="false"></div>
    
  3. To add the reviews container to a page, add the following HTML code:

    <div data-bv-show="reviews" data-bv-productId="ExternalId"></div>
    

    The data-bv-show data attribute instructs the BV loader to display reviews, and data-bv-productId instructs the BV loader to display the feature for a specified product ID, which must match the ExternalId provided in the product catalog.

  4. To add the questions container to a page, add the following HTML code:

    <div data-bv-show="questions" data-bv-productId="ExternalId"></div>
    

    The data-bv-show data attribute instructs the BV loader to display questions and answers, and data-bv-productId instructs the BV loader to display the feature for a specified product ID, which must match the ExternalId provided in the product catalog.

Show hidden content

Some user actions cause Bazaarvoice features to come into view, such as clicking the ★★★★★ icons in the rating summary, which scrolls to ratings and reviews. If this content is hidden behind a tab, however, you must add custom, page-specific code that calls the bvCallback function to show the correct tab or container.

Add the bvCallback function to the page so that the BV loader can download and execute it when the BV loader is downloaded (asynchronously). Then, include code in the bvCallback function to run a custom function.

For example, you can include a callback to the show event using the BV.reviews.on method when reviews come into view. (The BV.questions.on method is also available.) This example uses the bootstrap tab component:

<!DOCTYPE html>
<html lang="en">
  <head>
      <!-- Download the BV loader file. This replaces bvapi.js in Conversations v1 implementations.
        In the URL, replace <client_name>, <site_ID>, and <locale>, and replace <environment> with 'staging' or 'production'.
      -->
      <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/<environment>/<locale>/bv.js"></script>
  </head>
 
  <body>
      <!-- schema.org Markup: 
            itemscope and itemprop="name" are required for BV's injected schema.org 
            properties and metadata to be parsed correctly by search engines 
      -->
      <div itemscope itemtype="https://schema.org/Product">
           <!-- Product name must be identified with itemprop=name attribute-->
           <h1 itemprop="name">ProductName</h1>
 
          <!-- Rating summary goes above the fold near product name or image -->
          <div data-bv-show="rating_summary" data-bv-productId="ProductID123"></div>
 
          <!-- Content Tabs -->
          <div id="review_tab" style="display: none;">
            <!-- Instruct BV loader to show the R&R feature for productID123 here -->
            <div data-bv-show="reviews" data-bv-productId="productID123"></div>
          </div>
 
          <div id="questions_tab" style="display: none;">
            <!-- Instruct BV loader to show the Q&A feature for productID123 here -->
            <div data-bv-show="questions" data-bv-productId="productID123"></div>
          </div>
 
          <script>
            // bvCallback must be used when interacting with BV via JavaScript and using the `async` attribute. 
            window.bvCallback = function (BV) {
          
          // Register a function to be called when a BV feature needs to display the R&R element, such as Rating Summary's stars
              BV.reviews.on('show', function () {
                 // If the R&R container is hidden (such as behind a tab), put code here to make it visible (open the tab)
                 $('#review_tab').show();
              });
           
          // Register a function to be called when a BV feature needs to 
          // display the Q&A element, such as when clicking on the number of questions link
              BV.questions.on('show', function () {
                // If the container is hidden (such as behind a tab), put code here to make it visible (open the tab) 
                $('#questions_tab').show();
              });
            };
          </script>
      </div>
  </body>
</html>

Clean up existing PRR implementations

If Bazaarvoice code is currently integrated on your site, ensure that the new BV loader framework works properly by following these steps:

  1. Make sure no <script> tags or dynamic scripts reference bvapi.js.
  2. Remove any of the following attributes:
    • id=”BVRRSummaryContainer”
    • id=”BVRRContainer”
    • id=”BVQASummaryContainer”
    • id=”BVQAContainer”
  3. Remove any code that relies on $BV, such as calls to $BV.configure or $BV.ui.

  4. If Bazaarvoice SEO is implemented, update the implementation to remove references to BVRRSummaryContainer, BVRRContainer, BVQAContainer, and $BV calls. The SEO implementation must now reference the <div> tags described above.

Troubleshooting

If the rating summary or reviews are not displayed after you add this integration code, or if reviews are not styled correctly, BV loader is probably not inferring the correct hostname or display code. A network request error for bvapi.js may be displayed in the console. You can add the following attributes to the BV loader to override the display code that BV loader inferred:

<script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/<environment>/<locale>/bv.js">
  data-bv-display-code="<displaycode>"
  data-bv-hostname="reviews.<client_name>.com"
</script>

Loading question and answer content

Note: If you added integration code for the rating summary container ("fast stars"), follow the instructions in that section to add a questions container and skip the steps in this section.
  1. Place the following code within the head element.

    <script type="text/javascript" 
        src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
    </script>
    <script type="text/javascript">
        $BV.configure("global", {
            submissionContainerUrl: "http://www.client.com/submissionPage.html"
        });
    </script>
    

    Where:

    • submissionContainerUrl is the URL for the submission container page.
    • /bvstaging is removed from the URL before launching in your production environment.
    • $BV.configure calls are executed prior to any $BV.ui calls that they affect.
    • bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the “Loading the API Asynchronously” section for additional information. Asynchronous content loading is not common.
    Note:  For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain links are clicked. This warning page is normal for development and staging purposes and is common if you are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.

    After you confirm that the URL presented on the warning page is the URL that you want to use for development, it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.
  2. Place the following div element on every product and category page that you want to display the questions and answers summary:

    <div id="BVQASummaryContainer"></div>
    
  3. Place the following div element on every product and category page that you want to display the actual questions and answers:

    <div id="BVQAContainer"></div>
    

    After you add the div elements to the appropriate product and category pages, proceed to the following topics to integrate question and answer:

Integrating question and answer with product pages

  1. Verify that the div elements described in “Loading question and answer content” have been inserted.
  2. Make the following $BV.ui() call to load content into the div elements that you inserted:

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

    where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that is associated with the product in the data feed. It is recommended that this code is placed in the head.

Integrating question and answer with category pages

  1. Verify that the div elements described in “Loading question and answer content” have been inserted.
  2. Make the following $BV.ui() call to load question- and answer-related content into the appropriate div elements:

    <script type="text/javascript">
        $BV.ui("qa", "show_questions", {
            categoryId: "XXXXX",
            subjectType: "category"
        });
    </script>
    

    where XXXXX represents the ID of the current page’s category. This value must match the ID that is associated with the category in the data feed. It is recommended that this code is placed in the head.

Loading campaigns content

  1. Place the following code within the head element.

    <script type="text/javascript" 
        src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
    </script>
    <script type="text/javascript">
        $BV.configure("global", {
            submissionContainerUrl: "http://www.client.com/submissionPage.html"
        });
    </script>
    

    Where:

    • submissionContainerUrl is the URL for the submission container page.
    • /bvstaging is removed from the URL before launching in your production environment.
    • $BV.configure calls are executed prior to any $BV.ui calls that they affect.
    • bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the “Loading the API Asynchronously” section for additional information. Asynchronous content loading is not common.
    Note:  For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain links are clicked. This warning page is normal for development and staging purposes and is common if you are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.

    After you confirm that the URL presented on the warning page is the URL that you want to use for development, it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.
  2. Place the following div element on every product and category page that you want to display the campaign summary:

    <div id="BVSYSummaryContainer"></div>
    
  3. Place the following div element on every product and category page that you want to display the content:

    <div id="BVSYContainer"></div>
    

    After you add the div elements to the appropriate product and category pages, proceed to the following topics to integrate campaigns:

Integrating campaigns with product pages

  1. Verify that the div elements described in “Loading campaigns content” have been inserted.
  2. Make the following $BV.ui() call to load content into the div elements that you inserted:

    <script type="text/javascript">
        $BV.ui("sy", "show_stories", {
            productId: "XXXXX",
            subjectType: "product"
        });
    </script>
    

    where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that is associated with the product in the data feed. It is recommended that this code is placed in the head.

Integrating campaigns with category pages

  1. Verify that the div elements described in “Loading campaigns content” have been inserted.
  2. Make the following $BV.ui() call to load campaign-related content into the appropriate div elements:

    <script type="text/javascript">
        $BV.ui("sy", "show_stories", {
            categoryId: "XXXXX",
            subjectType: "category"
        });
    </script>
    

    where XXXXX represents the ID of the current page’s category. This value must match the ID that is associated with the category in the data feed. It is recommended that this code is placed in the head.