You can solicit customer reviews outside of the typical product review submission scenario. The generic review submission feature, also referred to as “product picker,” enables your customers to select the product or products they want to review. Generic review submission significantly expands your ability to collect valuable review feedback outside the typical product purchase cycle.

You can provide generic review submission links in email messages. For example, as part of an email campaign to solicit product reviews, you can email customers who have purchased from you in the past. Even if you don’t know which products they purchased, you can email them a generic “Write a review” link. Using this link, your customers can open a review submission form and then use the product picker interface to select one or more products they want to review.

You also can provide a generic review submission link on these pages:

  • Category pages
  • Landing pages
  • Special promotional pages

To enable generic review submission, you must decide whether to use the Bazaarvoice-hosted solution or configure site-hosted submission. You might choose to use Bazaarvoice-hosted generic review submission in the following situations:

  • You do not want to host the "Write a review" button and subsequent container on your site.
  • You want to link directly to the generic review submission feature from an email message or marketing campaign.

In either case, you can use a container page that resides on a Bazaarvoice server.

When a consumer clicks the review submission link, a lightbox is displayed and shows a set of products to review. The initial set of products can belong to a category or product family.

  • A category-based view allows reviewers to search and navigate in and out of sub-categories. Here is an example for the Bikes category:

  • A product-based view displays only products included in the specified product family. In the following example, the product family is WomensBikes:

Use Bazaarvoice-hosted generic review submission

To use the Bazaarvoice-hosted generic review submission, use query string parameters to control the container page actions. Use this link to display the hosted form:

https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic

Remove /bvstaging if you are in the production environment, and replace the following with your values:

  • <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.
  • <locale>—The locale used by the implementation. If you are not using US English (en_US), use the correct locale code.

You also can add one or more of the following options to the URL:

  • To prevent the consumer from closing the form, add the bvpreventClose=true parameter. If you do not include this parameter, the icon is displayed (as shown in the example above), and the consumer can close the form, which then displays the locale's home page as configured in the configuration hub.

    https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvpreventClose=true
  • To limit the products displayed on the form to a specific category, add the bvcategoryId=CategoryId parameter. CategoryId must match the category's <ExternalId> in the product feed.

    https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvcategoryId=<CategoryId>
  • To limit the products displayed on the form to a specific product family, add the bvfamilyProductId=ProductId parameter. Replace ProductId with the <ExternalId> of a product that belongs to the product family that you want to display. You can find the ExternalId for a product in the product catalog.

    https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvfamilyProductId=<ProductId>
  • To associate reviews submitted through the generic review submission form with a specific campaign, specify the bvcampaignId=CampaignId parameter. CampaignId is a string of up to 255 alphanumeric characters (including underscores) created to identify the campaign. Specify a custom ID or specify a system ID; refer to the list of campaign IDs that are provided with Conversations.

    https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvcampaignId=<CampaignId>

Enable site-hosted generic review submission

The following general steps explain how generic review submission works if you enable site-hosted generic review submission:

  1. Add the JavaScript integration code in order to load a Bazaarvoice-hosted JavaScript file (bv.js) on the page where you want the product picker to appear.
  2. Add a <div data-bv-show="product_picker"> element onto the page. If you want to trigger the product picker after the user clicks on a button or link, you can insert this element dynamically in a click event handler.
  3. Add other attributes to the <div data-bv-show="product_picker"> element to control which products are shown in the product picker and whether the picker is displayed in a lightbox.

To set up site-hosted generic review submission on your site, complete the steps in the following sections.

Note: Before setting up this feature, make sure proper mappings exist in your product feed. The product feed defines all products that will appear in the product picker. Those products are displayed only if categories or product families are appropriately mapped to products. Modify your product feed if those mappings do not exist.

Step 1: Add the JavaScript integration code

Add the following JavaScript integration code where you want the product picker to appear:

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

In the <script> element, replace the following with your values:

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

Step 2: Add a <div> with the product picker bv-data-show attribute

Add a <div> tag on the page with a product picker data-bv-show attribute:

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

With the default configuration above, the product picker will render into this element.

You can configure the product picker with additional optional attributes:

  • data-bv-category-id—Defaults to the root category. You can display a different category by specifying its ExternalId in the product feed. If the chosen category has subcategories, they will appear in a category drop-down in the breadcrumbs area.
  • data-bv-family-product-id—ID of a product in the family of products to be displayed.
  • data-bv-inline—Defaults to true. If inline mode is on, the product picker will render into the element with the data-bv-show attribute. If inline mode is off (data-bv-inline="false"), the product picker will render in a lightbox.
  • data-bv-prevent-close—Defaults to false. If data-bv-prevent-close="false", the product picker lightbox will have a close button. If true, the lightbox will display without a close button, and the user will not be able to close it once it is opened.

    Note: This attribute is ignored if data-bv-inline="true", as inline product pickers never have a close button.

Use one of the following configurations, depending on whether you want the product picker to feature products from your root category, another specified category, or a product family.

Root category-based products

In this scenario, you provide reviewers with a list of all products, enabling them to navigate through your entire category hierarchy into subcategories to find a product to review.

It does not define a data-bv-category-id value, so all defined categories will be included in the product picker.

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

The following example shows the product picker when no data-bv-category-id is specified, so all categories are available.

Specified category-based products

In this scenario, you provide the reviewer with a list of products associated with a category you select, allowing them to browse through any subcategories defined for that category.

Note: This use case is a best practice for category listing pages.

Insert the data-bv-category-id attribute in the product picker <div> tag, replacing ExternalId with the product category's ExternalId that is defined in the Bazaarvoice product catalog. It should be equal to the CategoryExternalId for each product in the category.

<div data-bv-show="product_picker" data-bv-category-id="ExternalId"></div>

The following example shows the product picker when data-bv-category-idis a top-level category called "car-seats." As a result, the Car Seats category and its subcategories are available.

Product family-based

In this scenario, you provide the reviewer with a list of all products that belong to a defined family.

Insert the data-bv-family-product-id attribute in the product picker <div> tag. Replace ProductId with the ExternalId of a product that belongs to the product family that you want to display. You can find the ExternalId for a product in the product catalog.

For example, assume you want to display your "MensBikes" product family. Identify a specific product in that family, such as the Endurance Challenger 1 men's road bike, and enter its ExternalId as the value for data-bv-family-product-id. The product picker element would identify that the product belongs to the "MensBikes" product family and display all products in that family.

<div data-bv-show="product_picker" data-bv-family-product-id="ProductId"></div>

The following example shows the product picker when you define a "MensBikes" family, which includes several models of bicycles. All products in the defined family are available.

Caution: Do not specify both data-bv-family-product-id and data-bv-category-id. You can specify one of those attributes, or you can specify neither, in which case the product picker displays all products. Specifying both parameters will throw an error in the console.

Trigger the product picker with a button or link

Alternatively, if you want to trigger the product picker after the user clicks on a button or link, you can insert the element dynamically in a click event handler. Create an anchor tag or button that reviewers click to initiate the submission process.

For example, if your "Write a review" button is defined as

<button id="grs">Write a review</button>

you can specify a function to inject the product picker into a container <div> and attach an event listener to handle the click event of the element, as shown below:

<div id="grs_container"></div>
<script type="text/javascript">
function submitGeneric (event) {
  var elem = document.createElement('div');
  elem.setAttribute('data-bv-show', 'product_picker');
  // Set any other options you would like.
  elem.setAttribute('data-bv-category-id', 'sampleCategory');
  // Inject the element into the page.
  document.getElementById('grs_container').appendChild(elem);
}
document.getElementById('grs').addEventListener('click', submitGeneric);
</script>

Enable site-hosted generic review submission (bvapi.js)

Note: If your existing implementation uses the scout file (bvapi.js), complete the following steps instead to set up site-hosted generic review submission on your site.

The following general steps explain how generic review submission works if you enable site-hosted generic review submission:

  1. A Bazaarvoice-hosted JavaScript file (bvapi.js) runs on the page where you place a "Write a review" link.
  2. The submitGeneric() event handler is called by the onclick event for the submission link.
  3. When a reviewer clicks the link, a lightbox is displayed and shows a set of products to review. The initial set of products can belong to a category or product family, depending on the information provided to the $BV.ui call.

To set up site-hosted generic review submission on your site, complete the steps in the following sections.

Note: Before setting up this feature, make sure proper mappings exist in your product feed. The product feed defines all products that will appear in the product picker. Those products are displayed only if categories or product families are appropriately mapped to products. Modify your product feed if those mappings do not exist.

Step 1: Add the JavaScript integration code

Add the following JavaScript integration code where you want the link to appear:

<script type="text/javascript" src="https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>

Remove /bvstaging if you are adding code to the production environment, and replace the following with your values:

  • <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 log in to the configuration hub to verify.
  • <locale>—The locale used by the implementation. If you are not using US English (en_US), use the correct locale code.

Step 2: Define the submitGeneric function

Define the submitGeneric function to call $BV.ui with the following optional options, which you can specify as properties of an object that you pass as a third argument to $BV.ui:

  • categoryId—Defaults to the root category. You can display a different category by specifying its ExternalId. If the chosen category has sub-categories, they will appear in a category drop-down in the breadcrumbs area.
  • familyProductId—ID of a product in the family of products to be displayed.
  • preventClose—Removes the consumer's ability to close the lightbox. Closing the lightbox reveals a blank page.

The following example shows the function to specify in the onclick attribute of a "Write a review" button. The function also specifies the preventClose option:

function submitGeneric () {
  $BV.ui('rr', 'submit_generic',
  { preventClose : 'True' });
}

Use one of the following scripts, depending on whether you want the product picker to feature products from your root category, another specified category, or a product family.

Root category-based products

In this scenario, you provide reviewers with a list of all products, enabling them to navigate through your entire category hierarchy into subcategories to find a product to review.

Insert the following script after the JavaScript integration code. It does not define a CategoryID value, so all defined categories will be included in the product picker.

<script>
    function submitGeneric() {
       $BV.ui('rr', 'submit_generic', {
       });
    }
</script>

Specified category-based products

In this scenario, you provide the reviewer with a list of products associated with a category you select, allowing them to browse through any subcategories defined for that category.

Note: This use case is a best practice for category listing pages.

Insert the following script after the JavaScript integration code, replacing ExternalId with the ExternalId that is defined in the Bazaarvoice product catalog. It is also the CategoryExternalId for each product in the category.

<script>
    function submitGeneric() {
       $BV.ui('rr', 'submit_generic', {
          categoryId : 'ExternalId'
       });
    }
</script>

Product family-based

In this scenario, you provide the reviewer with a list of all products that belong to a defined family.

Insert the following script after the JavaScript integration code, replacing ProductID with the product's ExternalId defined in the product catalog.

<script>
    function submitGeneric() {
       $BV.ui('rr', 'submit_generic', {
          familyProductId : 'ProductID'
       });
    }
</script>

Step 3: Specify a function to handle the onclick event

Specify a function to handle the onclick event of the element. You can create an anchor tag or button that reviewers click to initiate the submission process. Set the onclick attribute to a value of submitGeneric().

For example, define a simple anchor tag to initiate the submission process as:

<a onclick="submitGeneric()">Click here to write a review</a>
Note: You can use jQuery to attach submitGeneric to the click event. If you want the product picker to appear when the page loads, call the UI method directly instead of including it in the body of the submitGeneric function.

Use jQuery to attach events

If your page contains jQuery, you can use it to attach the submitGeneric function to the click event.

For example, if your "Write a review" button is defined as

<button id="bv-write-a-review">Write a review</button>

you can attach an event listener by using jQuery's on method, shown below:

jQuery('#bv-write-a-review').on('click', function () {
  $BV.ui('rr', 'submit_generic', {
    categoryId : 'shop'
  });
});

For Bazaarvoice-hosted generic review submission, use this link to display the hosted form:

https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvpreventClose=true

Remove /bvstaging if you are adding code to the production environment, and replace <client_name>, <site_ID>, and <locale> with your values.

For site-hosted generic review submission, add a generic review submission form to a specific page on your site by completing these steps:

  1. Include bv.js.
  2. Add a product picker <div> tag on the page with a special data-bv-show attribute:
    <div data-bv-show="product_picker"></div>

    You can include data-bv-category-id="ExternalId" or data-bv-family-product-id="ProductFamilyID" to display a specific category or product family in the product picker drop-down list. You can also set data-bv-inline to choose how the product picker renders on the page.

    Alternatively, you could define a "Write a review" button using this code:

    <button id="grs">Write a review</button>

    Attach an event listener to handle the click event and inject the product picker into the container <div>, as shown in the following example:

    <div id="grs_container"></div>
    <script type="text/javascript">
    function submitGeneric (event) {
      var elem = document.createElement('div');
      elem.setAttribute('data-bv-show', 'product_picker');
      // Set any other options you would like.
      elem.setAttribute('data-bv-category-id', 'sampleCategory');
      // Inject the element into the page.
      document.getElementById('grs_container').appendChild(elem);
    }
    document.getElementById('grs').addEventListener('click', submitGeneric);
    </script>  

Note: If your existing implementation uses the scout file (bvapi.js), complete the following steps instead to set up site-hosted generic review submission on your site:

  1. Include bvapi.js.
  2. Define a “Write a review” button using this code:
    <button id="bv-write-a-review">Write a review</button>
  3. Attach an event listener by using jQuery’s on method, as shown in the following example:
    jQuery('#bv-write-a-review').on('click', function () {
      $BV.ui('rr', 'submit_generic', {
        categoryId : 'shop'
      });
    });

    You can use familyProductId : 'productId' or categoryId : 'categoryId' within $BV.ui to display a specific product family or category in the product picker drop-down list .