To display user-generated content (UGC) collected by Bazaarvoice on your website, you must add Bazaarvoice code to your website. This enables your website to communicate with the Bazaarvoice application and retrieve consumer-generated content for display.

After adding display code to your site, customize each module’s look and feel on your pages as described in Hosted display configuration.

This topic describes the steps your technical team should take to:

  • Integrate Bazaarvoice UGC (Ratings & Reviews, Questions & Answers) into your product display pages, as well as steps to display hidden content
  • Integrate schema.org (SEO) into your product display pages
Note: Adding schema.org markup to your product pages helps major search engines extract and display useful information, such as product star ratings or product review snippets, in search engine results pages (SERPs). This is powerful when you consider that 95% of consumers read reviews before making a purchase.

Overview of the display modules

Most brands and retailers add Bazaarvoice display module code to their product display pages (PDPs), but you can add the code to all your pages if they use a shared template. In general, the following statements apply to all modules. Exceptions are documented in the following sections.

  • Display module content is updated continually as moderation approves submitted content.
  • Native and syndicated reviews that pass moderation are included in each display module.
  • All locales are supported.
  • Product families are supported.

Rating summary

The rating summary module, also called “fast stars,” displays the following information about the specified product ID:

  • 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
  • Number of questions and answers for the product

The module also provides “Write a review” and “Ask a question” links.

The rating summary is typically placed at the top of the PDP next to the product image to provide a summary of the ratings. Here is an example:

Rating Summary

Complete these steps to implement the rating summary:

Bazaarvoice strongly recommends that you implement this module with the reviews module, which is described next.

Reviews

The reviews module displays a list of ratings and reviews from each consumer who submitted a review. If comments are enabled and consumers submit comments to a review, the comments are also displayed by this module. Reviews are typically placed below the product image and description.

Here is an example:

Reviews container

Complete the following steps to implement reviews:

Bazaarvoice strongly recommends that you implement this module with the rating summary module, which is described in the previous section.

Review Highlights

The Review Highlights module shows a high-level summary of positive, neutral, and negative ratings and reviews. This display module enables consumers to gain immediate insight about a product without having to read individual product reviews, though they can expand a highlight to see the full review. To display this content, Bazaarvoice analyzes all ratings and reviews submitted for a specific product. Content featured in the display module is chosen randomly and updated between 2:00-3:00 AM Central Time (CST: UTC-6 or CDT: UTC-5).

Here is an example:

Review Highlights

Before implementing this module, be aware of the following requirements and limitations:

  • A product must have at least 10 native or syndicated reviews for the Review Highlights module to display.
  • Review Highlights cannot be displayed inside the reviews display module.
  • The Review Highlights module is available only for English locales.

If the Review Highlights module stops displaying, the associated product likely had fewer than 10 reviews when the module last refreshed (2:00-3:00 AM Central Time). The Review Highlights module will be displayed after at least 10 reviews are submitted for the product.

Complete the following steps to implement Review Highlights:

The Review Highlights module may take up to 48 hours to display after you enable and implement the feature.

Tip: Review Highlights Data is also available for API. To learn more, visit the Product Sentiment Insights API page in the Bazaarvoice Developer Portal.

Questions & Answers

This module shows questions and answers provided by consumers for the specified product ID. Questions and answers are typically placed below the product image and description.

Here is an example:

Questions container

Complete the following steps to implement Questions & Answers:

Add Bazaarvoice code to your website

To display consumer-generated content (CGC), such as ratings and reviews, you must add Bazaarvoice code to your website pages.

Caution: If your existing implementation uses the scout file (bvapi.js), refer to the Display integration v1 documentation. However, 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") and Review Highlights features. The code for these features will not work if Support does not enable them.

Step 1: Add the BV loader

The BV loader is a small, asynchronous JavaScript application that manages and displays configured features and CGC on your web pages. The BV loader will only download the required applications requested on the specific page.

To integrate the BV loader, add the following to your HTML within the <head> tag of the page:

<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.
Caution: If you have already added the BV loader while implementing BV Pixel or DCC, do not add it again. Add the BV loader only once per page.

Step 2: Add display modules for the CGC features

Add code to the <body> of a page where CGC features should be displayed.

If you are unfamiliar with data attributes, visit the Using Data Attributes page.

Note: After you add code to your site, customize how content is displayed on your pages as described in Hosted display configuration.

Product display page

You can add code for the following features on product display pages (PDPs):

Rating summary—The rating summary module, also called fast stars, displays a summary of information about the specified product ID.

  • Location: Bazaarvoice recommends placing the rating summary module above the fold, as close to the product name and image as possible.

  • Required HTML code for this feature:

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

    The data-bv-show data attribute instructs the BV loader to display the rating summary, and data-bv-product-id 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 for the same product 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-product-id="ExternalId"></div>
    ...
    <div data-bv-show="rating_summary" data-bv-product-id="ExternalId" data-bv-seo="false"></div>
    Caution: Only use rating summary modules for one product per page. You can have more than one rating summary per page, but they must all be for the same product. To show multiple rating summaries for multiple products on a single page, such as on a category listing page, use inline ratings instead.

Reviews—The reviews module displays a list of ratings and reviews from each consumer who submitted a review.

  • Location: Bazaarvoice recommends placing reviews below the fold, lower on the PDP.

    Caution: Bazaarvoice does not recommend placing reviews behind a tab. If your reviews will be displayed behind a tab, see Show hidden content.
  • Required HTML code for this feature:

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

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

Questions & Answers—The Questions & Answers module shows questions and answers provided by consumers for the specified product ID.

  • Location: Bazaarvoice recommends placing Questions & Answers below the main review display, lower on the PDP.

  • Required HTML code for this feature:

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

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

Review Highlights—The Review Highlights module shows a high-level summary of positive, neutral, and negative ratings and reviews.

  • Location: Bazaarvoice recommends placing Review Highlights below the product image (above the fold, if possible, or right below the fold) so consumers can see this as they scroll the page for product information.

  • Required HTML code for this feature:

    <div data-bv-show="review_highlights" data-bv-product-id="ExternalId"></div>

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

Product listing or category page

You can add code for the following feature on product listing or category pages:

Inline ratings—You can display inline ratings on a product listing or category page, product recommendation carousel, or search results page to provide a summary of ratings for products or services. Bazaarvoice calls inline ratings code only once per page, regardless of how many modules you display.

  • Location: Bazaarvoice recommends placing inline ratings below the product name.

  • Required HTML code for this feature:

    <div data-bv-show="inline_rating" data-bv-product-id="ExternalId-1"></div>
    <div data-bv-show="inline_rating" data-bv-product-id="ExternalId-2"></div>

    The data-bv-show data attribute instructs the BV loader to display inline ratings, and data-bv-product-id 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 include a hyperlink in an inline rating, add the data-bv-redirect-url=”<http://mycompany.com/product1> data attribute to the inline rating <div> tag.

Home page

Seller Ratings—The Seller Ratings module displays up to 12 four- and five-star reviews on your home page, which are refreshed daily. It also enables your seller ratings to appear in inline search results.

  • Location: Bazaarvoice recommends placing Seller Ratings below the fold on your home page.

  • Required HTML code for this feature:

    <div data-bv-show="seller_ratings"></div>

    The data-bv-show data attribute instructs the BV loader to display Seller Ratings for the client that matches the <client_name> provided in the header <script> tag. Note that Google Seller Ratings must be enabled for at least 24 hours before the feature appears on your site.

Full code example

The following example contains most of the code you must add to each PDP. 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>
      <!--
       First, download the BV loader file. This replaces bvapi.js in Conversations v1 implementations

       Replace <client_name>, <site_ID>, and <locale> with your values; 
       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>
          <!-- Rating summary - typically goes above the fold near product name or image -->
          <div data-bv-show="rating_summary" data-bv-product-id="ProductID123"></div>

          <!-- Review Highlights - typically goes below the product description or image -->
          <div data-bv-show="review_highlights" data-bv-product-id="ProductID123"></div>

          <!-- Reviews module for productID123 here -->
          <div data-bv-show="reviews" data-bv-product-id="productID123"></div>

          <!-- Questions module for productID123 here -->
      <div data-bv-show="questions" data-bv-product-id="productID123"></div>
  </body>
</html>

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>
          <!-- Rating summary goes above the fold near product name or image -->
          <div data-bv-show="rating_summary" data-bv-product-id="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-product-id="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-product-id="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>
  </body>
</html>

Add schema.org markup

Read the following sections to learn about schema.org markup:

What is a rich snippet?

Customers often find products through search engines. Adding schema.org markup to your product detail pages (PDPs) makes it easier for search engines to display snippets of consumer reviews in the search engine results page (SERPs). This is powerful when you consider that 95% of consumers read reviews before making a purchase.

Rich snippets such as star ratings or a review summary can enhance search results and increase organic click-through rates.

Note: Google extracts and displays rich snippet data from structured markup (such as schema.org ) in your website.

Here’s an example of a rich snippet:

Rich snippet example

Rich snippets are also known as “rich results”.

Why add schema.org markup?

Schema.org markup helps search engines such as Google, Yahoo, and Bing to understand your site’s content and display rich search results.

Adding schema.org markup has the following benefits:

  • Helps your content stand out on search results pages
  • Allows you to tag rich snippets to increase click-through rate (CTR)
  • Improves search engine ranking (indirectly); as improving CTR is a ranking influencer
  • Aligns with industry standards
Note: You’re responsible for ensuring that your JSON-LD objects are compatible with Bazaarvoice’s JSON-LD.

There are dozens of rich snippet types available but only a handful apply to retail and brand websites. AggregateRating and Review are two of the most valuable markup types you can add to Bazaarvoice Ratings & Reviews user-generated content (UGC).

  • AggregateRating : This snippet type gives search engines the number of aggregated reviews and star rating (out of 5) for a product.

  • Review : This snippet type gives search engines specific review related information about a product.

Schema.org formats (JSON-LD vs Microdata)

Bazaarvoice supports structured data in two formats:

  • JSON-LD
  • Microdata

Google has officially announced that JSON-LD is their preferred format for structured data. JSON-LD is simpler and cleaner to implement:

  • You can pack JSON-LD markup into your HTML pages in a standalone block.
  • You have to wrap Microdata markup around inline HTML elements.
Format Description and placement
JSON-LD (Recommended) JSON-LD stands for JavaScript Object Notation for Linked Data. JSON is a lightweight data-interchange format, which is easy for humans to read and write, and easy for machines to parse and generate. Instead of adding schema.org attributes to individual elements on a page (Microdata format), JSON-LD allows you to mark rich snippets you want to expose in a stand-alone block of JavaScript code. This makes JSON-LD structured data easy to add, update, or remove.
Note: Embed your JSON-LD structured code in a <script> tag in the head section of your HTML page.
Microdata Microdata uses HTML tag attributes to mark the content you want to expose as structured data. Microdata structured data communicates the same information that JSON-LD does. However, using the microdata format can be messy as structured data is nested inline within the HTML content.
Note: Microdata is embedded in <div> tags and typically placed inline to elements in your HTML page’s Document Object Model (DOM).

Why should I switch to JSON-LD?

Note: Bazaarvoice recommends that existing clients (who are using Microdata formatted markup) migrate to JSON-LD markup. Google isn’t requiring one format over another. However, it’s recommended to migrate to JSON-LD markup to future-proof content.

If your user-generated content is not delivered in the preferred format, your website is less likely to appear in a high rank position in shoppers’ search results. This can mean missed opportunities to organically acquire new customers.

Using JSON-LD, all of your structured data is packed into a standalone block of JavaScript code that goes into a header section of your HTML page.

Migrate from Microdata to JSON-LD?

If switching from Microdata structured data format:

Note: JSON-LD is enabled by default for new Conversations clients.

Add JSON-LD schema.org markup

Complete these steps to add JSON-LD schema.org markup.

Note: This topic describes how to add schema.org JSON-LD structured markup to your product display pages. The server side BVSEO SDK only supports Microdata formatted markup. Refer to Microdata structured markup for information on how to add Microdata formatted markup.

Step 1: Enable JSON-LD

Note: This step is completed by default for new clients. This step only applies if you’re switching from Microdata to JSON-LD format.
  1. Sign in to the Bazaarvoice Workbench.
  2. Select Settings » Manage Applications. The Site Manager page appears.
  3. From the Implementations list, locate the Conversations implementation where you want to configure SEO settings. Click Edit next to the implementation to open the configuration hub.
  4. Select SEO on the left side of the page under Settings. The SEO page appears.
  5. Make selections for each of the following SEO options for your implementation:

    • AggregateRating tag location—Google will only display rich snippet stars for pages with one schema.org AggregateRating tag. Choose a location from the following options to insert this tag:

      • Primary Ratings Summary (default)—Inserts the AggregateRating tag on the primary rating summary page. Bazaarvoice recommends this option.
      • Reviews Container—Inserts the AggregateRating tag at the top of the reviews container.
      • Remove Aggregate Rating tag—Excludes the AggregateRating tag.
    • SEO Markup Type—Select SEO JSON-LD Markup from the drop-down.

  6. Redeploy your implementation.

Step 2: Update product JSON-LD markup on your PDPs

Ensure you have valid JSON-LD markup on your product page and update the following:

  1. Add or update the @id property with the page URL.

    Note: If a canonical URL is specified on the page, use this URL instead.
  2. Remove any references to rating, review, aggregaterating, and other schema.org definitions from your existing JSON-LD Product object. These will be provided via the Bazaarvoice JSON-LD markup.

    This example illustrates what your JSON-LD structured data should look like:

    <html>
    <head>
    <title>Product Page</title>
     <script type="application/ld+json">
         {
         "@context" : "https://schema.org",
           "@type" : "Product",
           "@id" : "https://yourdomain.com/product-url",
           "name" : "Name of Product",
           "image" : "image url",
           "description" : "this is the product description",
           "sku" : "Product1",
           "brand" : "PopularBrand"}
     </script>
       <script id="bv-jsonld-aggregate-rating-data" type="application/ld+json">
         { "@context": "http://schema.org",
           "@id": "https://domainofclient.com/product-url",
           "aggregateRating": {
             "@type": "AggregateRating",
             "bestRating":5,
             "ratingValue":3.8,
             "reviewCount":1070
           }
         }
       </script>
     
    Note: The @id value in the Product markup should match the @id URL value in the JSON-LD markup injected by Bazaarvoice. Bazaarvoice JSON-LD elements, such as AggregateRating and Review, should be included in the same @type (most likely “Product”).
  3. Validate the schema.org markup on each PDP.

    Note: You are responsible for validating the schema.org markup on each PDP.

Step 3: Validate JSON-LD schema.org markup

Bazaarvoice recommends you use the Google Structured Data Testing tool or the Rich Results Test tool to validate your markup and identify any errors.

Note: These validation steps assume that you are using Chrome, Safari, or Firefox. The following steps, although they relate to using Google’s testing tools, apply whether you're validating JSON-LD or the Microdata markup format.

To test your schema.org markup integration:

  1. Navigate to your product display page (PDP) to ensure that the Summary AND the Reviews containers are both displaying on the page. By default, Bazaarvoice’s AggregateRating schema.org markup is only injected if the Summary container is on the page. The same applies to the Review schema.org markup and the Reviews container.

  2. Verify the correct JSON-LD blocks are being injected into the product display page by using the Elements inspector from your browser’s Developer Tools.

    • To open the Elements inspector, right-click a product display page to open the context menu. Choose Inspect to open the Developer Tools.

      Note: These testing tools rely on the active HTML in the browser. Using View > Developer > View Source (Option-Command-U on OS X) will only show the server-rendered HTML. Using Inspect will access the markup that Conversations injects dynamically.
    • Open search by pressing Ctrl+F (Command-F on OS X) and type ld+json to find all of the JSON-LD blocks on the page. Press Enter or click the down arrow to continue searching.

      Ensure there is a block providing the aggregateRating key and another providing the review key. Then, validate that the @id attribute with the product page URL matches the injected blocks. The example below uses @id”:”https://domainofclient.com/product-url in the blocks for the aggregateRating key and the review key. If you have additional display elements, such as head-to-head reviews, you might see additional injected JSON-LD blocks.

      Rich snippet example
  3. Select the Elements tab in the Developer Tools and find the schema.org markup. For example, the < html ... > element. Right-click and select Copy > Copy Outer HTML. Make sure you copy the entire DOM for valid results.

    Rich snippet example
  4. In a new tab, open the Google Structured Data Testing tool or the Rich Results Test tool.

  5. Go to CODE SNIPPET and paste the HTML you copied.

    Rich snippet example
  6. Select RUN TEST. Google will then show you how it interprets any structured data it finds. Check the schema.org markup for two things:

    • Is Product a top-level element?
    • Are Reviews correctly nested under Product?

    The Google Structured Data Testing tool will detect errors and/or warnings.

    Rich snippet example
    • If errors are detected, select the errors report to find the source of the problem code.
    • Review the warnings and confirm they are caused by your existing code. JSON-LD markup unrelated to Bazaarvoice code is outside the scope of support.
  7. (Optional) To check a product element (without errors), select PREVIEW. This will show you how rich snippets will look in the SERPs.

    Note: This is usually a routine check unless you have multiple top-level elements such as “Product”, “Organization”, or “Webpage."

Common questions

Yes. JSON-LD will work if you are using either bv.js or bvapi.js.

Schema.org is a collaborative standards initiative (set up by Google, Bing, and Yahoo in 2011) to promote industry standards for improving the web. Schema.org markup uses a form of structured metadata that you add to your PDPs to help search engines return richer search results pages to customers. You don’t need to learn any new coding skills. Schema.org markup uses Javascript (JSON) syntax.

Microdata is schema.org markup added inline to a webpage’s DOM. Nested microdata often derives its meaning and connections based on the structure of content on a page.

No. JSON-LD format is not supported in our legacy ratings and reviews product.

JSON-LD is not supported for Q&A. Continue to use the Microdata format for Q&A.

Clean up existing implementations of Conversations

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=”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 in Add Bazaarvoice code to your website.

Note: Other features of Conversations do not yet support the updated syntax of the display integration code that uses data-bv-show. For these features, Bazaarvoice recommends that you follow step 1 in Integrate tabs or other dynamic content to create the bvCallback function and then add any $BV.configure or $BV.ui calls that are specific to those features in that function.

Single-page application support

If your website is a single-page application (SPA), the BV loader is fully supported.

Our MutationObserver monitors your site’s HTML containers with the bv-data-show attribute. Once a Bazaarvoice container is on the page and registered, if any of your scripts update the data-bv-product-id, data-bv-subject-id, or any other data property recognized by our API, the BV loader will handle the rest by:

  • Reinitializing any namespaces
  • Fetching API data from the browser cache or the web
  • Redrawing any applications within the new page setup

For example, call the following methods to dynamically set attributes in containers with bv-data-show:

document.querySelector('[data-bv-show="reviews"]').setAttribute('data-bv-product-id', 'product2');
document.querySelector('[data-bv-show="rating_summary"]').setAttribute('data-bv-product-id', 'product2');