Product Picker (Generic review submission)

You can solicit customer reviews outside of the typical product review submission scenario. Product Picker (formerly generic review submission) enables consumers to select the product or products they want to review. It significantly expands your ability to collect valuable review feedback outside the typical product purchase cycle.

In-depth Quick Start

You can provide Product Picker 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 Product Picker link on these pages:

Category pages
Landing pages
Special promotional pages

To enable Product Picker, you must decide whether to use the Bazaarvoice-hosted solution or configure site-hosted submission. You might choose to use Bazaarvoice-hosted Product Picker 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 Product Picker 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 selects 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 "Playground" category:
A product-based view displays only the products included in the specified product family. In the following example, the product family is "Music":

Use Bazaarvoice-hosted Product Picker

To use the Bazaarvoice-hosted Product Picker, 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. Use lowercase letters for the value.
<site_ID>—The ID of the deployment zone you want to use. This is set in Bazaarvoice configuration within the Bazaarvoice Workbench. The default deployment zone is “main_site”. Check with your Bazaarvoice representative to ensure the correct ID, or select to the right of the deployment zone on the Site Manager page during configuration.
<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 page.
```
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=ProductFamilyID parameter. Replace ProductFamilyID with the <ExternalId> of 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=<ProductFamilyID>
```
To associate reviews submitted through the Product Picker 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 Ratings & Reviews .
```
https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/container.htm?bvaction=rr_submit_generic&bvcampaignId=<CampaignId>
```

You can also use the Submission Link Generator to create the simple submission URL (ssURL) base.

Note: To access the Submission Link Generator in Support Community, sign in to the Bazaarvoice Portal first. Then, select the Access the Support Community link located at the bottom of the Home page or top of the Help window. To open the Help window, select the Help icon in-app help icon

in the upper-right corner.

Enable site-hosted Product Picker (`bv.js`)

The following steps explain how Product Picker works when you enable site-hosted Product Picker:

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.
Add a <div data-bv-show="product_picker"> element onto the page. If you want to trigger the Product Picker after the user selects a button or link, you can insert this element dynamically in a click event handler.
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. These products can belong to a category or product family depending on the information provided to the $BV.ui or BV.ui call.

To set up site-hosted Product Picker 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. Use lowercase letters for the value.
<site_ID>—The ID of the deployment zone you want to use. This is set in Bazaarvoice configuration within the Bazaarvoice Workbench. The default deployment zone is "main_site". Check with your Bazaarvoice representative to ensure the correct ID, or sign in to configuration 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` tag with the product picker `data-bv-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 dropdown 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, campaign ID, 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"></divgt;

The following example shows the Product Picker when data-bv-category-idis a top-level category called "Playground." As a result, the Playground category and its subcategories are available.

Family-based products

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 ProductFamilyID with the ExternalId of 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="ProductFamilyID"></div>

The following example shows the Product Picker with the product family defined as "Art". All art-related products in this 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.

Campaign ID

Add the following code to inject campaign ID to the hidden field of review submission form:

<div data-bv-show="product_picker" data-bv-campaign-id="TestCampaignID"</i>"></div>

Trigger the Product Picker with a button or link

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

You can also use the following example to handle click events for the Write a review button. The function also specifies the preventClose option:

        <script type="text/javascript">
        function submitGeneric() {
        BV.ui('rr', 'submit_generic', {
        campaignId: 'SampleProduct'
        preventClose: true
        inline: true
        })
        </script>

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>

Required parameters

The following table identifies the required parameters/fields:

Parameter	Description
`rr`	Required string parameter.
`submit_generic`	Required string parameter.
`campaignId`	ID element used to help segment data in reports to a specific campaign or campaigns.

Optional parameters

Parameter	Description
`categoryId`	Id string value of the category. Do not pass if `familyProductId` is passed.
`familyProductId`	Id string value of specific product family. Do not pass if `categoryId` is passed.
`inline`	Defaults to `false`. If `true`, it shows the application inline instead of as a modal by default.

Enable site-hosted Product Picker (`bvapi.js`)

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

The following steps explain how Product Picker works if you enable site-hosted Product Picker:

A Bazaarvoice-hosted JavaScript file (bvapi.js) runs on the page where you place a "Write a review" button.
The submitGeneric() event handler is called by the onclick event for the submission link.
When a reviewer selects 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 Product Picker on your site, complete the steps in the following sections.

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. Use lowercase letters for the value.
<site_ID>—The ID of the deployment zone you want to use. This is set in Bazaarvoice configuration within the Bazaarvoice Workbench. The default deployment zone is “main_site”. Check with your Bazaarvoice representative to ensure the correct ID, or sign in to configuration 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 dropdown in the breadcrumbs area.
ProductFamilyID—ID of the product family to be displayed.
preventClose—Removes the consumer's ability to close the lightbox. Closing the lightbox reveals a blank page.
campaignId—Used to help segment data in reports to a specific campaign or campaigns. Bazaarvoice recommends you include this parameter; refer to the list of campaign IDs that are provided with Ratings & Reviews.

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:

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

Use one of the following scripts, depending on whether you want the Product Picker to feature products from your root category, campaign ID, 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>

Family-based products

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 : 'ProductFamilyID'
       });
    }
</script>

Campaign ID-based products

Insert the following script to inject campaign ID so that the submission form includes this information in the review form’s hidden fields:

<script>
    function submitGeneric() {
       $BV.ui('rr', 'submit_generic', {
          campaignId : 'TestCampaignId'
       });
    }
</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 select 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 Product Picker, 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 Product Picker, add a Product Picker form to a specific page on your site by completing these steps:

Include bv.js.

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 dropdown 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 Product Picker on your site:

Include bvapi.js.

Define a “Write a review” button using this code:

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

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 ProductFamilyID: 'productId' or categoryId : 'categoryId' within $BV.ui to display a specific product family or category in the Product Picker dropdown list .

Pop out

Ratings & Reviews

Learn

Implement

Collect content

Product catalog

Display content

Manage content

Analyze data

View insights

Create reports

Analytics for API

Integrate analytics

Product Picker (Generic review submission)

Use Bazaarvoice-hosted Product Picker

Enable site-hosted Product Picker (`bv.js`)

Step 1: Add the JavaScript integration code

Step 2: Add a `div` tag with the product picker `data-bv-show` attribute

Root category-based products

Specified category-based products

Family-based products

Campaign ID

Trigger the Product Picker with a button or link

Required parameters

Optional parameters

Enable site-hosted Product Picker (`bvapi.js`)

Step 1: Add the JavaScript integration code

Step 2: Define the submitGeneric function

Root category-based products

Specified category-based products

Family-based products

Campaign ID-based products

Step 3: Specify a function to handle the onclick event

Use jQuery to attach events

Select your language:

Pop out

Ratings & Reviews

Learn

Implement

Collect content

Product catalog

Display content

Manage content

Analyze data

View insights

Create reports

Analytics for API

Integrate analytics

Use Bazaarvoice-hosted Product Picker

Enable site-hosted Product Picker (bv.js)

Step 1: Add the JavaScript integration code

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

Root category-based products

Specified category-based products

Family-based products

Campaign ID

Trigger the Product Picker with a button or link

Required parameters

Optional parameters

Enable site-hosted Product Picker (bvapi.js)

Step 1: Add the JavaScript integration code

Step 2: Define the submitGeneric function

Root category-based products

Specified category-based products

Family-based products

Campaign ID-based products

Step 3: Specify a function to handle the onclick event

Use jQuery to attach events

Support

Feedback

Language

Print

Toggle dropdowns

Remove highlights

Enable site-hosted Product Picker (`bv.js`)

Step 2: Add a `div` tag with the product picker `data-bv-show` attribute

Enable site-hosted Product Picker (`bvapi.js`)