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.

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

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

Configure display settings

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 before going live.

Before beginning, be sure to

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. If a Spotlights deployment zone does not exist, click Add deployment zone and create with a descriptive name.
  4. In the Implementations section of the page, ensure that Spotlights Implementation exists. If a Spotlights implementation does not exist, create one by clicking Copy implementation at the top of the Implementations section. Select the implementation to copy and specify Spotlights Implementation in the Name field.
  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 the header text that is displayed above the Spotlights display module on your pages:
    1. Click Copy Editor on the left side of the page under User Experience.
    2. Scroll down to the Spotlights section of the page.
    3. Hover over the last row in the table and click the Edit button. The row description states "This field can be used to provide header for the Spotlight. Token {SpotlightName}, if present, will be replaced with the Spotlight name."
    4. Enter the header text in the New Value(s) field.
  7. 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 with CSS overrides

If you chose to use the Bazaarvoice stylesheet (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.

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 feed. 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. You can create the definitions file using a variety of spreadsheet authoring programs.

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 display settings.
  4. Name the file spotlights.csv and upload the file as described below.
  5. Notify your Bazaarvoice implementation team that you have uploaded your test definitions file.

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: Override the definitions file

You can selectively override specified columns of information in your primary Spotlights definition file. The following examples illustrate situations in which you might find this useful.

  • Overriding for SEO management—Some organizations have dedicated SEO specialists who work remotely or on a different schedule from the rest of their developers. By maintaining a Spotlights definitions override file that contains only keyword information, you can ensure that your dedicated SEO team can use a workflow that suits them and does not interrupt the work of your other developers.
  • Overriding for testing—You might want to override one or more columns in your definitions file to test what effect the changes will have before changing the primary file. If you work with Bazaarvoice to perform A/B tests, we use this method to perform the tests.

You can use multiple override files, such as if one department controls SEO keywords for a particular subset of products and a different department controls SEO keywords for a different subset of products.

Complete the following steps to create and upload a Spotlights definitions override file.

  1. Create a CSV spreadsheet that is similar to your Spotlights definitions file but includes only the ExternalId column as well as the columns you want to override. For example, an overrides file for SEO keywords might include ExternalId, KeywordsExact, KeywordsTracked, and KeywordsExcluded columns.

    Note: Refer to Spotlights definitions file reference for a full description of each column you can use in your file.
  2. Name the file using the following format: sequence-owner_name-YYYYMMDD.csv, where sequence is a two-digit number specifying the order to process the override file, owner_name is the business owner of the file, and YYYYMMDD is the date the file was created. For example, an overrides file might be named 01-bob_smith-20160201.csv.

    Note: If you use an overrides file to perform A/B tests, use a sequence number of 99 for that file to ensure that it is processed last.
  3. Upload the Spotlights override file to the spotlights-inbox/delta folder, as described in the next step.
Note: Overrides files remain in effect until they are removed from the SFTP folder.

Step 3: Upload the definitions file

Upload your Spotlights definitions file to one of the Bazaarvoice SFTP servers. Bazaarvoice processes Spotlights definitions files once each day.

  • Upload your Spotlights definitions file to the spotlights-inbox folder.
  • Upload any Spotlights definitions override files to the spotlights-inbox/delta folder.
Note: Use the same SFTP login and credentials that you use to upload your product feed.

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

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.

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 feed. 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 feed. 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 feed. 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 id="BVSpotlightsContainer"></div>

JavaScript source element

A <script> element with a src attribute referencing the full path to the Bazaarvoice scout.js file. The path includes your unique cloud key.

Requirements:

  • Load only once.
  • Place before the Spotlights display module rendering call.
  • Form the path to the scout.js file as follows, using the cloud key provided to you by Bazaarvoice and the root folder you specify in your Spotlights definitions file.
    http://seo.bazaarvoice.com/
    <CLOUD_KEY>/<ROOT_FOLDER>/
    spotlights/scout.js

Example:

<script src="http://seo.bazaarvoice.com/demo-af027b01370af4598c3011ebfd1c3a87/Spotlights-en_US/spotlights/scout.js">
</script>

Spotlights display module rendering call

A <script> element containing a call to the BV.Spotlights.render function. You can specify parameters to customize the rendering of the Spotlights display module.

Requirements:

  • Load only once. Client-side deployment supports only one Spotlights display module per page. Attempting to call the render function more than once results in an error.
  • Do not add code that waits for the document to be ready or delays making the initial call to the BV.Spotlights.render function. Doing so could prevent search engines from crawling the content. The Spotlights code loads resources asynchronously, so rendering occurs as soon as possible.

Example:

<script>
    BV.Spotlights.render({
    contentType: 'spotlights',
    subjectId : 'SL-demo'
                        });     
</script>
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 code examples

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

  • Cloud Key:demo-af027b01370af4598c3011ebfd1c3a87
  • 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 demo-af027b01370af4598c3011ebfd1c3a87 with the cloud key provided during implementation and SL-demo with the ExternalId in your Spotlights definitions file.

<html>
<body itemscope="" itemtype="http://schema.org/WebPage">
	<div id="BVSpotlightsContainer"></div>	
	<script src="http://seo.bazaarvoice.com/demo-af027b01370af4598c3011ebfd1c3a87/Spotlights-en_US/spotlights/scout.js"></script>
	<script>
	     BV.Spotlights.render({
	    	 contentType: 'spotlights',
	    	 subjectId : 'SL-demo'
	     });     
	</script>
</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>
<body itemscope="" itemtype="http://schema.org/WebPage">
	<div id="BVSpotlightsContainer"></div>
	<script src="http://seo-stg.bazaarvoice.com/demo-af027b01370af4598c3011ebfd1c3a87/Spotlights-en_US/spotlights/scout.js"></script>
	<script>	     
	     BV.Spotlights.render({
	    	 contentType: 'spotlights',
	    	 spotlightId : 'SL-demo'
	     });     
	</script>
</body>
</html>

Localize Spotlights

Spotlights offers several localization features. You can: