Implement > Display > Spotlights

Spotlights

Spotlights provides you with a configurable display module that enables you to leverage consumer-generated content (CGC) on pages that typically do not include it, such as category, list, and landing pages. Each Spotlights display module can provide the following:

  • 1,000 to 6,000 words of rich, social content on pages that often hold little content
  • Language that your customers use to describe and search your products
  • Product images and reviews for product categories that you define

By displaying products and services loved by the community, you improve the consumers' experience and boost their confidence in your site and business. You also make your pages significantly more search-friendly. Pages that display a Spotlights module typically:

  • Display rich snippet stars in search results for Google and Bing.
  • Improve in search rank.
  • Have a reduced bounce rate.
  • Rank well for additional search phrases.
Note: While Spotlights content is marked up to adhere to Google and Bing’s rich snippets guidelines, rich snippets are dependent on both Google and Bing indexing and are not guaranteed. Additional rich snippet information can be found here.

This section provides the tasks you must complete to configure and display Spotlights.

Define Spotlights instances

You must create a Spotlights definitions file that defines each of your Spotlights instances. The definitions file specifies the products and categories to include in each instance using the product ID and category definitions from your product catalog. Each row in the definitions file defines a separate Spotlights instance. The definitions file also defines keywords that are used for SEO.

The definitions file is saved in comma-separated value (CSV) format and UTF-8 encoded. You can create the definitions file using a variety of spreadsheet authoring programs.

Note: EMEA clients need to ensure the CSV file is saved as UTF-8, as that is not a common encoding standard.

Step 1: Create the definitions file

Complete the following steps to create your Spotlights definitions file.

  1. Download the sample Spotlights definitions file to use as a starting point.

  2. Create a test version of your definitions file by manually defining 5-10 Spotlights instances. Refer to the example items in the file as well as the Spotlights definitions file field reference for information about how to define instances.
  3. Encode the definitions file to ensure maximum compatibility of characters outside the standard US English alphabet, including special characters such as the copyright symbol (©) or diacritical marks such as umlauts (ü). By default, Bazaarvoice uses UTF-8 encoding. If you want to encode the definitions file using an encoding type other than UTF-8, be sure to configure this setting as described in Configure Spotlights display.
  4. The file name must be spotlights.csv. This is required.

Once you determine that your definitions file functions appropriately, complete the file by adding additional Spotlights instances.

Note: Bazaarvoice recommends that you automate the creation of the Spotlights definitions file and then upload an updated version daily. This ensures that Spotlights instances do not become stale as your product catalog changes. If you prefer to manually manage your definitions file, discuss doing so with your Bazaarvoice implementation team.

Step 2: Upload the definitions file

Upload your Spotlights definitions file to the appropriate Bazaarvoice SFTP server. Bazaarvoice processes Spotlights definitions files once each day.

  • Upload your Spotlights definitions file to the spotlights-inbox folder.
Note: Use the same SFTP login and credentials that you use to upload your product catalog.

Bazaarvoice recommends uploading your files to both the staging and production folders:

  • If your data is hosted in the US, use the following URLs:
    • Staging server—sftp-stg.bazaarvoice.com
    • Production server—sftp.bazaarvoice.com
  • If your data is hosted in Europe, use the following URLs:
    • Staging server—sftp7-stg.bazaarvoice.com
    • Production server—sftp7.bazaarvoice.com

Be sure to connect to SFTP using port 22. If you do not know your SFTP credentials or where your data is hosted, contact Bazaarvoice Client Care.

Notify your Bazaarvoice implementation team that you have uploaded your test definitions file.

Note: Spotlights definitions files process every morning at 2:00 AM CST.

Spotlights definitions file reference

The Spotlights definitions file is a spreadsheet which you save in comma-separated values (CSV) format. You can create the definitions file using any software program, but be sure to encode the file in UTF-8 format if you use special characters such as the copyright symbol (©) or diacritical marks such as umlauts (ü).

Each row in the Spotlights definition file represents a separate Spotlights instance. You can place the columns in any order.

Refer to Define Spotlights instances for more information about working with the file once you have created it.

Localize Spotlights

Spotlights offers several localization features. You can:

Deploy Spotlights

Spotlights can be deployed using the following methods. You can only use one of the methods to deploy Spotlights on any given page.

  • Server-side deployment—This method is universally search-friendly. Using a software development kit (SDK) that we provide, you deploy code on your page and on your server that supplies your page with relevant consumer generated content (CGC). Bazaarvoice recommends this method for maximum SEO boost and minimum page loading times.
  • Client-side deployment—This method requires less development overhead on your part. You implement JavaScript in your page, which displays relevant CGC. Major search engines, primarily Google and Bing, now crawl and index content served using JavaScript. If your site relies on search traffic from search engines other than Google and Bing, this method provides you with less SEO benefit. For more information about the new JavaScript indexing capability exhibited by major search engines, see this blog post . Refer to this blog post to understand how Google crawls web pages.
Note: If you plan to deploy Spotlights on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

Prerequisites for deployment

To deploy Spotlights using either of the two methods, you must have the following items:

  • Cloud Key—Provided by Bazaarvoice
  • Root Folder—RootFolders configured in your Spotlights definitions file
  • Subject ID—ExternalID configured in your Spotlights definitions file

Best practices

Before deploying Spotlights, observe these best practices:

  • Place Spotlights deployment code on all existing category pages. Bazaarvoice also recommends implementing Spotlights on keyword-targeted landing pages. Pages not containing live Spotlights instances should be identified as control group pages.

  • Place the Spotlights module at the bottom of the page, above any linking modules and footers.
  • When using client-side deployment, Bazaarvoice recommends including the appropriate schema.org/WebPage declaration in the body element of your pages as shown in the following example:

    <body itemscope="" itemtype="http://schema.org/WebPage">

    If you cannot add the itemscope and itemtype attributes to the <body> element, you can make the declaration in a <div> or <span> element. However, the schema.org/WebPage declaration must span the entire body contents of the page.

Server-side deployment

This deployment method is universally search-friendly. Using the Bazaarvoice SEO software development kit (SDK), you can deploy code on your page and on your server that supplies your page with relevant consumer generated content (CGC). Bazaarvoice recommends this method for maximum SEO boost and minimum page loading times.

Note: If you plan to deploy Spotlights on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

Bazaarvoice offers SDKs for three different environments. Each of the following links takes you to the full documentation for the corresponding SDK, including implementation instructions, downloads, and code examples. Also, be aware that SDKs are not exclusively used for Spotlights. Look for Spotlights example code within the documentation for each SDK.

Note: In most cases, Bazaarvoice recommends using a production call to the Bazaarvoice integration code. Doing so allows you to test Spotlights behavior in your staging environment using reviews from your production database.

Client-side deployment

This deployment method requires less development overhead on your part. You implement JavaScript in your page, which displays relevant CGC. Major search engines, primarily Google and Bing, now crawl and index content served using JavaScript. If your site relies on search traffic from search engines other than Google and Bing, this method provides you with less SEO benefit. For more information about the new JavaScript indexing capability exhibited by major search engines, see this blog post .

Note: If you plan to deploy Spotlights on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

To use client-side deployment, you must place the following elements into the markup for your page. Refer to Client-side deployment code examples for full code examples showing client-side deployment under different scenarios.

Spotlights container


A <div> element that determines where the Spotlights display module is placed.

Place the Spotlights display module at the bottom of the page, above any linking modules and footers.

Example:

<div data-bv-show="spotlights" data-bv-subject-id="SL-Demo" data-bv-site-id="Spotlights"></div>

Add the following attributes to the <div> tag:

  • data-bv-show="spotlights"—Call needed to show Spotlights widget.
  • data-bv-subject-id—Subject ID needed by the Spotlights application.
  • data-bv-site-id—Name of the deployment zone from which your Spotlights application is built. Capitalize each word and separate each word with an underscore. Your Spotlights deployment zone is created by default, so the data-bv-site-id will be "Spotlights".

JavaScript source element


A <script> element with a src attribute referencing the full path to the BV loader bv.js file.

Add the following JavaScript integration code inside the <head> element of the page:

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

In the <script> element, replace the following:

  • <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 for Spotlights is "spotlights". Check with your Bazaarvoice representative to ensure the correct ID, or log in to the configuration hub to verify.
  • <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 used by the implementation. If you are not using US English (en_US), use the correct locale code.

Client-side deployment code examples

The following examples show client-side Spotlights deployment code in different scenarios. The examples use the following configuration information:

  • Root Folder: Spotlights-en_US
  • Subject ID: SL-Demo

Client-side integration in a production environment

The following example code shows client-side Spotlights deployment code in a production environment. Replace SL-demo with the ExternalID in your Spotlights definitions file.

<html>
<head>
  <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/production/<locale>/bv.js"></script>
</head>
<body itemscope="" itemtype="http://schema.org/WebPage">
  <div data-bv-show="spotlights" data-bv-subject-id="SL-Demo" data-bv-site-id="Spotlights"></div>
</body>
</html>

Client-side integration in a staging environment

The following example shows client-side Spotlights deployment code in a staging environment. Using a staging environment enables you to test changes before deploying to production. Specify a staging path in the src attribute of the JavaScript source element, as shown in the following code.

<html>
<head>
  <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/staging/<locale>/bv.js"></script>
</head>
<body itemscope="" itemtype="http://schema.org/WebPage">
  <div data-bv-show="spotlights" data-bv-subject-id="SL-Demo" data-bv-site-id="Spotlights"></div>
</body>
</html>

Note: If your existing implementation uses the scout file (bvapi.js), you must place the following elements into the markup for your page instead. Expand the section below and refer to Client-side deployment code examples (bvapi.js) for full code examples showing client-side deployment under different scenarios.

Configure Spotlights display

Using the Conversations configuration hub, you must configure the display settings for the Spotlights display module, as well as settings for contacting members of your company.

Note: Users of the legacy PRR platform might encounter limited display irregularities that can be corrected by contacting Bazaarvoice Client Care before going live.

Complete these steps to configure the Spotlights display settings:

  1. Log in to the Bazaarvoice Workbench.
  2. Select Settings » Manage Applications.
  3. In the Deployment Zones section of the Site Manager page, ensure that deployment zones exist for both Main Site and Spotlights.
  4. In the Implementations section of the page, ensure that Spotlights Implementation exists.
  5. Click Edit next to the Spotlights Implementation.
    Note: Adjusting Spotlights settings in a deployment zone other than the Spotlights deployment zone has no effect.
  6. To customize product eligibility settings, click Spotlights on the left side of the page under Settings and then configure these settings:
  7. Configure these settings to customize the Spotlights display template:

  8. To customize the header text that is displayed above the Spotlights display module on your pages, complete the following steps:

  9. To customize all other Spotlights settings, click Spotlights on the left side of the page under Settings and then configure these settings:

Before deploying these changes to production, be sure to thoroughly test your Spotlights deployment in the staging environment.

Customize Spotlights CSS

CSS Overrides

If you chose to use the Bazaarvoice style sheet (without cleanslate), complete the following steps to customize the visual styling of the Spotlights display module with your own CSS. 

  1. In your HTML markup, add a link to your CSS file below the Spotlights .css file link:
  2. <link rel="stylesheet" type="text/css" href="your-custom-styles.css" />
  3. Use specificity to override Spotlights base styles if necessary.
  4. spotlights.css

    .bv-cleanslate .bv-spotlights .bv-review-title { font-size: 1.2em; }

    your-custom-styles.css

       .your-parent-element .bv-cleanslate .bv-spotlights .bv-review-title { font-size: 2em; }
Note: Bazaarvoice does not support any changes you make to override the Bazaarvoice-hosted style sheets. Only advanced users should attempt to override the Bazaarvoice-hosted style sheets. You must thoroughly test your changes in a staging environment before moving them to production.

Client-hosted CSS

Bazaarvoice can provide the Spotlights CSS file to be hosted on your website.

Note: If you are going to host the Spotlights CSS file yourself, please notify your Spotlights team.

Grant access to Google Search Console

Complete the following steps to grant Bazaarvoice restricted access to your Google Search Console, which we use to track the search engine optimization (SEO) impact of Spotlights and to provide you with accurate reports.

  1. Navigate to your Google Search Console and log in with administrator rights. A list of the properties you own appears.
  2. Click the Manage property menu to the right of the property to which you are adding Spotlights.
  3. Select Add or remove users. The Users and Property Owners screen appears.
  4. Click Add a new user.
  5. Type seoreporting@bazaarvoice.com in the User email field and select Restricted in the Permission menu.
  6. Click Add.

Grant access to Google Analytics

To track the search engine optimization (SEO) impact of Spotlights and to provide accurate reporting, you must grant read-only access of your Google Analytics account to Bazaarvoice. If you do not use Google Analytics as your analytics platform, contact Bazaarvoice Client Care to enable this capability.

Complete the following steps to grant Bazaarvoice read-only access to your Google Analytics account:

  1. Sign in to your Google Analytics account as a user with administrator rights.
  2. Click the property to which you want to grant access.
  3. In the Account column, click User Management.
  4. In the Add permissions for field, type seoreporting@bazaarvoice.com and then select Read & Analyze from the drop-down menu.
  5. Click Add.
Note: If you do not use Google Analytics as your analytics platform, work with your Spotlights team to discuss alternate measurement strategies using your site analytics platform.

Need more help?