Você está na página 1de 81

Bazaarvoice

quick start
implementation
guide

Disclaimer
Copyright 2012 Bazaarvoice. All rights reserved.
The information in this document:
Is confidential and intended for Bazaarvoice clients. No part of this document may be shared with anyone outside
your company or your company-partners without prior approval from Bazaarvoice.
Is provided as is without warranty of any kind either expressed or implied, including, but not limited to the implied
warranties of merchantability, fitness for a particular purpose, or non-infringement.
Is periodically updated to be in sync with the improvements and/or changes in our product offers.
May be changed without notice. Some examples depicted herein are provided for illustration only and are not
guarantees of a specific result. You bear the risk of using this document.
Bazaarvoice is not liable for any technical or typographical errors that might be inadvertently present in this document.
Bazaarvoice might have patents and/or pending patent applications covering subject matter in this document. The
furnishing of this document does not give you any license to these patents, or legal rights to any other intellectual property
in any Bazaarvoice service or product.
All Bazaarvoice brand and product names are trademarks or registered trademarks of Bazaarvoice in the United States
and may be protected as trademarks or registered trademarks in other countries. All other product, service, or company
names mentioned here are claimed as trademarks and trade names by their respective companies.

Contact us:
3900 North Capital of Texas Highway
Suite 300, Austin, Texas 78746
Toll-Free: (866) 522-9227 | Phone: (512) 551-6000 | Fax: (512) 551-6001
www.bazaarvoice.com

TOC

Contents
Introduction..............................................................................................................................................6
Ratings and reviews......................................................................................................................................6
Question and answer....................................................................................................................................8
Campaigns..................................................................................................................................................9
Profiles.......................................................................................................................................................11
Prerequisites............................................................................................................................................13
Creating a subdomain for user-facing URLs.....................................................................................................13
Granting access to a development website....................................................................................................13
Providing a data feed..................................................................................................................................14
Integrating display features.......................................................................................................................15
Loading ratings and reviews content.............................................................................................................15
Loading question and answer content...........................................................................................................16
Integrating question and answer with product pages...........................................................................17
Integrating question and answer with category pages..........................................................................18
Loading campaigns content.........................................................................................................................18
Integrating campaigns with product pages.........................................................................................19
Integrating campaigns with category pages........................................................................................19
Loading profiles content..............................................................................................................................20
Adding the ROI beacon to transaction and conversion pages..........................................................................22
ROI beacon parameters...............................................................................................................................24
Rendering the submission container page...................................................................................................27
Implementing the submission container page..............................................................................................28
Implementing the login-redirection logic.......................................................................................................28
Rendering the submission container page.....................................................................................................30
Generating the user authentication string......................................................................................................30
Implementing Bazaarvoice SEO.................................................................................................................32
Create an automated process for daily tasks...................................................................................................32
Download and unpack SEO files........................................................................................................32
Inject SEO content on product pages.................................................................................................33
Ratings and reviews..............................................................................................................34
Question and answer............................................................................................................34
Campaigns..........................................................................................................................35
Perform a string replacement within the SEO files................................................................................36
Handle the SEO URL parameter.........................................................................................................36
Special case: When UGC is behind a tab........................................................................................................37
Verify your SEO implementation...................................................................................................................39
Implementation checklists.........................................................................................................................40
General checklist........................................................................................................................................40
Using advanced integration options............................................................................................................41
Loading the API asynchronously...................................................................................................................41
Implementing inline ratings.........................................................................................................................42
Method comparison........................................................................................................................43
Using the Bazaarvoice platform API for inline ratings (recommended approach)......................................43
Using ratings XML feed for inline ratings.............................................................................................44
Implementing login redirection with JavaScript..............................................................................................45
Integrating with AJAX-type login methods.....................................................................................................45

Bazaarvoice Confidential

TOC
Displaying content that resides behind a tab..................................................................................................46
Targeted link to Bazaarvoice content............................................................................................................47
Example formats: Targeted URLs.......................................................................................................47
Overriding redirect URLs..................................................................................................................48
Sharing content through Facebook...............................................................................................................49
Updating Facebook tags..................................................................................................................49
Creating an application for Facebook.................................................................................................50
Creating a new Facebook application.....................................................................................50
Using an existing Facebook application...................................................................................51
Same-page submission................................................................................................................................51
Implementing same-page submission with AJAX-type login methods.....................................................52
Implementing same-page submission with a separate login page..........................................................53
Implementing same-page submission................................................................................................55
Implementing ratings and reviews on your mobile site....................................................................................56
Using the event callback..............................................................................................................................56
Example: Event callback...................................................................................................................57
Event variables for ratings and reviews...............................................................................................57
Event variables for question and answer.............................................................................................58
Event variables for campaigns...........................................................................................................58
Event variables for all Bazaarvoice products........................................................................................59
Additional event variables................................................................................................................59
Appendix................................................................................................................................................64
JavaScript API details..................................................................................................................................64
Configuration calls..........................................................................................................................64
UI calls...........................................................................................................................................65
Ratings and reviews methods................................................................................................65
show_summary........................................................................................................65
show_reviews..........................................................................................................66
submit_review..........................................................................................................66
submit_comment......................................................................................................66
Question and answer methods..............................................................................................66
show_summary........................................................................................................67
show_questions.......................................................................................................67
show_search............................................................................................................67
submit_question.......................................................................................................68
submit_answer.........................................................................................................68
Campaigns methods............................................................................................................68
show_summary........................................................................................................68
show_stories............................................................................................................69
show_grid...............................................................................................................69
show_home.............................................................................................................69
submit_story............................................................................................................69
submit_comment......................................................................................................70
Profiles methods..................................................................................................................70
show_profile............................................................................................................70
submit_profile..........................................................................................................71
submission_container...........................................................................................................71
Additional configuration options.......................................................................................................71
Common display options.......................................................................................................71
Submission options..............................................................................................................73

Bazaarvoice Confidential

TOC
User authentication string options..........................................................................................74
Example: Integration code..........................................................................................................................75
Submission links.........................................................................................................................................76
Submission links for ratings and reviews.............................................................................................76
Submission links for question and answer...........................................................................................76
Submission links for campaigns.........................................................................................................78
Submission links for profiles..............................................................................................................79
Options for submission link parameters..............................................................................................79

Bazaarvoice Confidential

Bazaarvoice quick start implementation guide

Introduction
This document describes the tasks that are associated with implementing one or more Bazaarvoice products or
solutions. The intended audience consists of developers who need to implement such a product or solution quickly
and easily for Example Client.
The steps in this document utilize the Bazaarvoice QuickStart method to complete a successful implementation.
With the QuickStart method, Bazaarvoice handles the majority of the development work while our tools integrate
seamlessly with your existing teams and workflows. A typical QuickStart implementation consists of the following
tasks:
1. Integrating the display features, which consists of the following subtasks:
a. Adding the Bazaarvoice JavaScript API.
b. Loading the appropriate Bazaarvoice content.
2. Rendering the submission container page.
3. Implementing the submission container page, which consists of the following subtasks:
a. Implementing the appropriate login-redirection logic.
b. Rendering the submission container page.
c. Generating the user authentication string (UAS).
You can rely upon the Bazaarvoice implementation team to provide detailed guidance and support for each step
in the implementation process. If you have questions about the Bazaarvoice side of your implementation, contact
your Bazaarvoice Implementation Project Manager (IPM) or Implementation Engineer (IE).

Ratings and reviews


Bazaarvoice ratings and reviews lets your customers share their honest feedback directly within the purchase path
of your website. Such feedback fuels customer decision-making to drive sales, decrease product returns, and build
trust in your brand.

Bazaarvoice Confidential

Introduction
This document provides the information that you need to install and configure ratings and reviews. When you are
finished, the following components are added to your storefront:
Ratings summary Displays the overall rating of a product as well as information like the number of customers
who would recommend the product to a friend. The ratings summary also provides links for reading additional
reviews, writing a review, and sharing the relevant product through social networking sites like Facebook and
Twitter.
The following image shows an example ratings summary.

Primary display area Displays review-related content, as shown by the following image.

Bazaarvoice Confidential

Bazaarvoice quick start implementation guide

Question and answer


Bazaarvoice question and answer helps your customers make informed purchasing decisions by asking questions
and providing answers about relevant products. Insights that you gain from question and answer help you improve
your product copy based on the content that the community submits.
This document provides the information that you need to install and configure question and answer. When you
are finished, the following components are added to your storefront:
Q&A summary Displays information about the questions and answers that are available for the product, such
as the number of submitted questions and answers. The Q&A Summary also provides links for reading approved
content and asking a new question.
The following image shows an example Q&A Summary.

If no questions or answers are currently available, a Be the first to ask a question link is displayed.

Bazaarvoice Confidential

Introduction
Primary display area Displays question- and answer-related content, as shown by the following image.

Campaigns
Bazaarvoice campaigns makes it easy for you to collect and display real contentsuch as stories, ideas, testimonials,
or recipesfrom real customers, highlighting the degree to which your brand fits into their lives and helping you
stand out among competing brands. With campaigns, authentic customer content lives on your site and can be
shared across social networks like Facebook and Twitter.

Bazaarvoice Confidential

Bazaarvoice quick start implementation guide


This document provides the information that you need to install and configure campaigns. When you are finished,
the following components are added to your storefront:
Campaign summary Displays information about customer content, such as the number of approved items
that have been submitted for a product or service. The summary also provides links for reading submissions
and sharing new content.
The following image shows an example campaign summary.

Primary display area Displays question- and answer-related content, as shown by the following image.

10

Bazaarvoice Confidential

Introduction

Profiles
Bazaarvoice is committed to building online communities that drive measurable goals. With Bazaarvoice's profiles
feature, the opinions, knowledge, and experience of your most active customers come together to build trust in
your brand and to influence purchasing decisions. Profiles makes it easy to identify your most active contributors
by collecting uniform demographic information for each user and by displaying an aggregate of activity for each
user across all of your Bazaarvoice products.
In addition to featuring standard content like user nicknames, badges, and statistics, active profiles extends the
customer relationship by providing brand ambassadors with a platform for creating and maintaining an identity
on your site. Users are encouraged to include in their profiles personally descriptive information that they are
willing to share with the online community, as shown by the following examples:
Profile headline
Photos
Product recommendations
The ability to let customers include such information in their profiles is a feature that strengthens the community,
builds brand loyalty among your top customers, and increases the purchase likelihood for prospective buyers.

Bazaarvoice Confidential

11

Bazaarvoice quick start implementation guide


This document provides the information that you need to install and configure the profiles feature. When you are
finished, your storefront will feature profiles like the one in the following image.

12

Bazaarvoice Confidential

Prerequisites

Prerequisites
Ensure that the following prerequisites are satisfied before starting a Bazaarvoice integration:
Create a subdomain that points to Bazaarvoice servers for all user-facing URLs.
Grant Bazaarvoice access to a development website.
Provide Bazaarvoice with a production-ready data feed of your products.
The following sections describe these prerequisites in more detail.

Creating a subdomain for user-facing URLs


A subdomain that is used for all user-facing URLs including submission URLs, targeted links, and links to landing
pages must point to Bazaarvoice servers. All implementations require the creation of the following canonical
name (CNAME) entry for general user-generated content (UGC):
ugc.example.com -> example.ugc.bazaarvoice.com

On a Linux server, this entry resembles the following code:


ugc IN CNAME example.ugc.bazaarvoice.com ; BV cache network

Additionally, you must create the following, product-specific CNAME entries where appropriate:
For ratings and reviews, create the following CNAME entry:
reviews.example.com -> example.ugc.bazaarvoice.com

For question and answer, create the following CNAME entry:


answers.example.com -> example.ugc.bazaarvoice.com

For campaigns, create the following CNAME entry:


stories.example.com -> example.ugc.bazaarvoice.com

Granting access to a development website


Your technical team must grant Bazaarvoice access to a development website without the need for a VPN client
or other type of remote-desktop access, as per the details of your contract. The Bazaarvoice implementation team
requires browser access to your staging environment to complete the following tasks:
Style the product
Resolve cascading style sheets (CSS) conflicts

Bazaarvoice Confidential

13

Bazaarvoice quick start implementation guide


Assist with the resolution of code-integration issues
Perform functional testing
Test the graphical user interface (GUI)
No changes or updates are made to your code.
If your staging environment resides behind a firewall, open port 80 or a non-standard port of your choosing to the
following IP addresses and ranges:
IP Address

Location

24.155.144.5

Austin, USA

24.155.144.36

Austin, USA

216.166.20.0/26

Austin, USA

80.169.157.170

London, UK

123.51.122.10

Sydney, Australia

Bazaarvoice requires this level of access to your staging environment even after the implementation is finished.
New features, bug fixes, and updates must be verified against the staging environment before they can be rolled
into our production environment.

Providing a data feed


Your technical team must provide Bazaarvoice with an XML-based, production-ready data feed of the products
that you want to feature Bazaarvoice-hosted UGC. This feed is used to populate the Bazaarvoice database so that
the UGC and dimensions can be mapped to the appropriate products and categories, respectively. For more
information, refer to the Bazaarvoice Product Feed document.

14

Bazaarvoice Confidential

Integrating display features

Integrating display features


The following topics contain instructions for how to inject Bazaarvoice UGC on your site based on the features you
plan to implement.
The integration code in this section contains the path /bvstaging in its example URLs. This token routes requests
to the Bazaarvoice staging environment. It is recommended that you design your implementation of the Bazaarvoice
integration code in a manner that allows you to toggle easily between including or excluding the path /bvstaging
in or from the appropriate URLs. Ensure that /bvstaging is removed from the URLs in your production environment.

Loading ratings and reviews content


1. Place the following code within the <head> element.
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
submissionContainerUrl: "http://www.example.com/submissionPage.html"
});
</script>

Where:

submissionContainerUrl is the URL for the submission container page.

/bvstaging is removed from the URL before launching in your production environment.

$BV.configure calls are executed prior to any $BV.ui calls that they affect.

bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the "Loading

the API Asynchronously" section for additional information. Asynchronous content loading is not common.
Note
For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the
domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain
links are clicked. This warning page is normal for development and staging purposes and is common if you
are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.
After you confirm that the URL presented on the warning page is the URL that you want to use for development,
it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you
plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.

2. Place the following <div> element on every product page where you want to display the ratings summary:
<div id="BVRRSummaryContainer"></div>

Bazaarvoice Confidential

15

Bazaarvoice quick start implementation guide

3. Place the following <div> element on every product page where you want to display the actual reviews:
<div id="BVRRContainer"></div>

4. Make the following $BV.ui() call to load content into the <div> elements that you inserted during the previous
step:
<script type="text/javascript">
$BV.ui("rr", "show_reviews", {
productId: "XXXXX"
});
</script>

where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that
is associated with the product in the data feed. We recommend that you place this code in the <head> element.
Related Links
Implementing the submission container page on page 28
Loading the API asynchronously on page 41
JavaScript API details on page 64

Loading question and answer content


1. Place the following code within the <head> element.
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
submissionContainerUrl: "http://www.example.com/submissionPage.html"
});
</script>

Where:

submissionContainerUrl is the URL for the submission container page.

/bvstaging is removed from the URL before launching in your production environment.

$BV.configure calls are executed prior to any $BV.ui calls that they affect.

bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the "Loading

the API Asynchronously" section for additional information. Asynchronous content loading is not common.

16

Bazaarvoice Confidential

Integrating display features

Note
For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the
domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain
links are clicked. This warning page is normal for development and staging purposes and is common if you
are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.
After you confirm that the URL presented on the warning page is the URL that you want to use for development,
it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you
plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.

2. Place the following <div> element on every product and category page that you want to display the questions
and answers summary:
<div id="BVQASummaryContainer"></div>

3. Place the following <div> element on every product and category page that you want to display the actual
questions and answers:
<div id="BVQAContainer"></div>

After you add the <div> elements to the appropriate product and category pages, proceed to the following topics
to integrate question and answer:
Integrating question and answer with product pages
Integrating question and answer with category pages
Related Links
Implementing the submission container page on page 28
Loading the API asynchronously on page 41

Integrating question and answer with product pages


1. Verify that the <div> elements described in "Loading question and answer content" have been inserted.
2. Make the following $BV.ui() call to load content into the <div> elements that you inserted:
<script type="text/javascript">
$BV.ui("qa", "show_questions", {
productId: "XXXXX",
subjectType: "product"
});
</script>

where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that
is associated with the product in the data feed. It is recommended that this code is placed in the <head>.

Bazaarvoice Confidential

17

Bazaarvoice quick start implementation guide

Integrating question and answer with category pages


1. Verify that the <div> elements described in "Loading question and answer content" have been inserted.
2. Make the following $BV.ui() call to load question- and answer-related content into the appropriate <div>
elements:
<script type="text/javascript">
$BV.ui("qa", "show_questions", {
categoryId: "XXXXX",
subjectType: "category"
});
</script>

where XXXXX represents the ID of the current pages category. This value must match the ID that is associated
with the category in the data feed. It is recommended that this code is placed in the <head>.

Loading campaigns content


1. Place the following code within the <head> element.
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
submissionContainerUrl: "http://www.example.com/submissionPage.html"
});
</script>

Where:

submissionContainerUrl is the URL for the submission container page.

/bvstaging is removed from the URL before launching in your production environment.

$BV.configure calls are executed prior to any $BV.ui calls that they affect.

bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the "Loading

the API Asynchronously" section for additional information. Asynchronous content loading is not common.
Note
For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the
domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain
links are clicked. This warning page is normal for development and staging purposes and is common if you
are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.
After you confirm that the URL presented on the warning page is the URL that you want to use for development,
it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you
plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.
18

Bazaarvoice Confidential

Integrating display features

2. Place the following <div> element on every product and category page that you want to display the campaign
summary:
<div id="BVSYSummaryContainer"></div>

3. Place the following <div> element on every product and category page that you want to display the content:
<div id="BVSYContainer"></div>

After you add the <div> elements to the appropriate product and category pages, proceed to the following topics
to integrate campaigns:
Integrating campaigns with product pages
Integrating campaigns with category pages
Related Links
Implementing the submission container page on page 28
Loading the API asynchronously on page 41

Integrating campaigns with product pages


1. Verify that the <div> elements described in "Loading campaigns content" have been inserted.
2. Make the following $BV.ui() call to load content into the <div> elements that you inserted:
<script type="text/javascript">
$BV.ui("sy", "show_stories", {
productId: "XXXXX",
subjectType: "product"
});
</script>

where XXXXX represents the ID of the product that is displayed on the page. This value must match the ID that
is associated with the product in the data feed. It is recommended that this code is placed in the <head>.
Related Links
JavaScript API details on page 64

Integrating campaigns with category pages


1. Verify that the <div> elements described in "Loading campaigns content" have been inserted.

Bazaarvoice Confidential

19

Bazaarvoice quick start implementation guide

2. Make the following $BV.ui() call to load campaign-related content into the appropriate <div> elements:
<script type="text/javascript">
$BV.ui("sy", "show_stories", {
categoryId: "XXXXX",
subjectType: "category"
});
</script>

where XXXXX represents the ID of the current pages category. This value must match the ID that is associated
with the category in the data feed. It is recommended that this code is placed in the <head>.
Related Links
JavaScript API details on page 64

Loading profiles content


Bazaarvoice links to profile pages from the content that they generate. Because you are responsible for hosting
the profile container, you must inform your Bazaarvoice IE of the appropriate URL pattern for your profile pages,
using a wildcard for the user ID.
The following URLs provide examples of typical URL patterns:

http://www.example.com/profile.html?user=USERID

http://www.example.com/profile/USERID

1. Place the following code within the <head> element.


<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
submissionContainerUrl: "http://www.example.com/submissionPage.html"
});
</script>

Where:

submissionContainerUrl is the URL for the submission container page.

/bvstaging is removed from the URL before launching in your production environment.

$BV.configure calls are executed prior to any $BV.ui calls that they affect.

bvapi.js is not loaded asynchronously. If you need to load the API asynchronously, see the "Loading

the API Asynchronously" section for additional information. Asynchronous content loading is not common.

20

Bazaarvoice Confidential

Integrating display features

Note
For security reasons, Bazaarvoice configures a whitelist of allowable domains for your integration. If the
domain of the submissionContainerUrl is not included in the list, a warning page might appear when certain
links are clicked. This warning page is normal for development and staging purposes and is common if you
are developing against localhost, an IP, or another hostname of which Bazaarvoice is unaware.
After you confirm that the URL presented on the warning page is the URL that you want to use for development,
it is safe to pass through it. In production, Bazaarvoice must be made aware of all of the domains that you
plan to deploy. Additionally, the configured URLs must match the domains that you plan to deploy.

2. Place the following <div> elements within a single block on your profile pages:
<div id="BVCPBodyAContainer"></div>
<div id="BVCPBodyBContainer"></div>

3. Make the following $BV.ui() call to load profile-related content into the <div> elements that you inserted
during the previous step:
<script type="text/javascript">
$BV.ui("cp", "show_profile", {
profileId: "XXXXX"
});
</script>

where XXXXX represents the user ID that is associated with the profile page. Obtain this value from the URL
that you defined earlier in this topic. Do not encode the user ID like it is encoded on the submission page. It
is recommended that this code is placed in the <head>.
For information about additional API calls and customization options, see JavaScript API details on page 64.
Related Links
Implementing the submission container page on page 28
Loading the API asynchronously on page 41

Bazaarvoice Confidential

21

Bazaarvoice quick start implementation guide

Adding the ROI beacon to


transaction and conversion pages
Add the following JavaScript code to your transaction and conversion pages to enable the ROI beacon.
An example of a transaction page might be a purchase confirmation page. A conversion page is any page on your
site where you measure conversion activity. Some examples of conversion pages include a store locator results
page, a warranty registration completion page, or a site registration completion page.
1. Place the following code within the <head> element.
<script type="text/javascript"
src="//{{client_code}}.ugc.bazaarvoice.com/bvstaging/static/{{display_code}}/bvapi.js">
</script>
<script type="text/javascript">
$BV.SI.trackTransactionPageView({
/* add transaction or conversion JSON here */
});
</script>

Where:

22

{{client_code}} is your client code.

/bvstaging is removed from the URL before launching in your production environment.

{{display_code}} is your display code.

Bazaarvoice Confidential

Adding the ROI beacon to transaction and conversion pages

2. For transaction pages, supply the following data using the sample format.
$BV.SI.trackTransactionPageView({
"orderId" : "55555",
// REQUIRED
"tax" : "1.44",
"shipping" : "10.00",
"total" : "40.84",
// REQUIRED
"city" : "Austin",
"state" : "TX",
"country" : "USA",
"currency" : "USD",
// ISO 4217 alphabetic currency code
"locale" : "en_US",
// Used to send locale-specific post-interaction email (PIE)
"items" : [
{
"sku" : "2245",
// REQUIRED - Must match SKU on product display page!
"name" : "product name",
"category" : "category name",
"price" : "13.42",
// Used to sort products in PIE
"imageURL" : "http://product/image/URL/1",
"quantity" : "1"
// REQUIRED
},
{
"sku" : "2245",
// REQUIRED - Must match SKU on product display page!
"name" : "product name",
"category" : "category name",
"price" : "13.42",
"imageURL" : "http://product/image/URL/2",
"quantity" : "1"
// REQUIRED
}
],
"userId" : "7448dc2",
// REQUIRED
"email" : "john@example.com", // REQUIRED
"nickname" : "john1981",
// REQUIRED
"gender" : "M"
});

Important!
The SKU (product ID) that you include in your transaction data must match the SKU that you provide to
Bazaarvoice on your product display page. If the SKUs don't match, our analytics engine cannot correlate
consumer behavior to conversion.

3. For conversion pages, supply the following data as JSON using the sample format.
$BV.SI.trackConversion({
"type": "StoreLocator",
"label": "ProductPage",
"value": 78701
});

For our non-transactional /non-commerce clients, we still recommend tracking against your most important
goal. Non-transactional conversion goal examples include:
Download complete
Store locator results
Warranty registration
Site registration

Bazaarvoice Confidential

23

Bazaarvoice quick start implementation guide

ROI beacon parameters


These tables list parameters that you can include in your analytics JSON for transactions, transaction items,
conversions, and personally identifiable information.
Transaction parameters
Parameter

Required

Description

Example

orderId

yes

The unique ID of the order.

"55555"

tax

no

The amount of tax applied to the order.

"1.44"

shipping

no

The cost of shipping the order.

"10.00"

total

yes

The total amount of the order.

"40.84"

city

no

The customer's city.

"Austin"

state

no

The customer's state.

"TX"

country

no

The customer's country.

"USA"

currency

no

The ISO 4217 alphabetic currency code of the "USD"


order.

items

yes

The parameters associated with each item in


the order.

See the "Items


parameters" table.

Personally Identifiable Information (PII) parameters


The following transaction parameters are considered to be PII data. PII enables you to send a follow up email asking
the customer to return to your site and contribute content. This message, called a post-interaction email (PIE), helps
to increase content volume at your site.

24

Parameter

Required

Description

Example

userId

Yes

The unique ID of the user.

"7448dc2"

locale

no

Transaction locale. Use a two or four letter code. "de_DE" or "de"


Format is [language_code]_[COUNTRY_CODE]. Used
to send local-specific PIE.

email

Yes

The user's email address.

Bazaarvoice Confidential

"john@example.com"

Adding the ROI beacon to transaction and conversion pages

Parameter

Required

Description

Example

nickname

Yes

The nickname of the user. The nickname is used "john1981"


to address the user in the PIE.

gender

no

The gender of the user.

"M" or "F"

Important!
PII information:
is NEVER associated with the Bazaarvoice persistent cookie.
is ALWAYS transmitted over HTTPS.
is encrypted before writing to disk.
is NEVER processed by Bazaarvoice analytics.

Item parameters
Parameter

Required

Description

Example

sku

yes

The Bazaarvoice ExternalID of the item. Sometimes this is a SKU code "2245"
or ProductID, but it MUST match what you send to Bazaarvoice in
your product data feed for the <Product> <ExternalID>. If the
ExternalID you set for the sku parameter is NOT in your product data
feed, the product will NOT be included in the generated PIE that
goes to the consumer.

name

no

Product name.

"Black t-shirt"

Important!
Should match the value you provide to Bazaarvoice in the product
data feed.

category

no

Product category.

"Shirts"

Important!
Should match the value you provide to Bazaarvoice in the product
data feed.

price

no

Product price.

"13.42"

Important!
Must have only two fraction numbers after the decimal.

quantity

yes

Quantity purchased.

Bazaarvoice Confidential

"4"

25

Bazaarvoice quick start implementation guide

Parameter

Required

Description

Example

imageUrl

yes

Link to the product image, which is used to display the product in


the PIE.
Important!
Should match the value you provide to Bazaarvoice in the product
data feed. If you omit this value but provide a valid ExternalID, we
pull the imageUrl from our database.

Conversion parameters

26

Parameter

Required

Description

Example

type

yes

The type of conversion. You define the


value of this parameter.

"StoreLocator" or "Download"

label

no

A descriptive label for the conversion.

"ProductPage" or "Product
Specifications - 1234.pdf"

value

yes

A value to attribute to the conversion.

"78701" or "1"

Bazaarvoice Confidential

Rendering the submission container page

Rendering the submission container


page
A submission container page is used for all Bazaarvoice content submissions.
1. After the login-redirection logic is implemented, place the following example code within the <head> element
of the submission container page that you created:
<script type="text/javascript"
src="http://example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.ui("submission_container", {
userToken: "XXXXX"
});
</script>

where XXXXX represents the Bazaarvoice-encoded UAS. If you do not have a value to place in this location,
leave it blank.
2. Place the following code where you want the submission form to appear:
<div id="BVSubmissionContainer"></div>

The Bazaarvoice submission form is loaded within the BVSubmissionContainer <div> element.
Related Links
Generating the user authentication string on page 30

Bazaarvoice Confidential

27

Bazaarvoice quick start implementation guide

Implementing the submission


container page
A submission container page is used for all Bazaarvoice content submissions. Integrating the submission container
page consists of the following tasks.
Whenever users trigger the submission flow by clicking a submission link, Bazaarvoice redirects them to the
submission container page while passing URL parameters that are required for submission.
1. Implementing the login-redirection logic on page 28
2. Rendering the submission container page on page 27
3. Generating the user authentication string on page 30

Implementing the login-redirection logic


Before you build the submission container page, ensure that the server-side authentication code follows the
login-redirection logic that the following pseudocode represents:
if ( bvauthenticateuser == true && user is not logged in ) {
redirect to the login page
after the user logs in, redirect back to this submission page with all query string parameters
intact
} else {
continue rendering page
}

28

Bazaarvoice Confidential

Implementing the submission container page


This logic is based on the value of bvauthenticateuser, which is one of the many query string parameters that are
passed to the submission container page, and is illustrated by the following image.

The sections that are labeled Client controlled actions identify the behaviors that you are responsible for
implementing.

Bazaarvoice Confidential

29

Bazaarvoice quick start implementation guide

Rendering the submission container page


A submission container page is used for all Bazaarvoice content submissions.
1. After the login-redirection logic is implemented, place the following example code within the <head> element
of the submission container page that you created:
<script type="text/javascript"
src="http://example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.ui("submission_container", {
userToken: "XXXXX"
});
</script>

where XXXXX represents the Bazaarvoice-encoded UAS. If you do not have a value to place in this location,
leave it blank.
2. Place the following code where you want the submission form to appear:
<div id="BVSubmissionContainer"></div>

The Bazaarvoice submission form is loaded within the BVSubmissionContainer <div> element.
Related Links
Generating the user authentication string on page 30

Generating the user authentication string


If you are authenticating users, generate a UAS so that Bazaarvoice can determine whether a string comes from a
trusted source.
Consisting of key-value pairs, a UAS is signed and encoded through the use of a shared key. This string allows
Bazaarvoice to verify that it comes from a safe source, thereby preventing third parties from fabricating or
impersonating users.
The following table identifies the ampersand-delimited keys and values that can be used in the string.

30

Key

Description

Required

date

Today's date in the format YYYYMMDD or YYYY-MM-DD.

Yes

maxage

Number of days before the UAS expires. The default number of days is 1. Increasing this value No
is useful in pre-authenticated URLs, such as the URLs that are used in email campaigns.

userid

User's ID. Do not use email addresses.

Bazaarvoice Confidential

Yes

Implementing the submission container page


To enable verified purchaser badging via on-the fly simple submission method, you must add additional data to
your user authentication string. The subjectids and verifiedpurchaser strings are necessary for the badge to
show up.
A pre-encoded string must be UTF-encoded, and its values must be URL-escaped. For example, the string Exam
ple$tring must be rendered as Example%24tring. The following code provides an example pre-encoded string.
date=2007-05-27&userid=ID12345

Perform the following steps to encode a string:


1. Generate the hex MD5 hash of the shared key, concatenated with the UAS.
Use the following value for the shared key:
12345678901234567890123456789012345678901234567890123456789012345

The resulting string is 32 characters in length.


2. Hex encode the UAS.
3. Concatenate the result of step 1 with the result of step 2.
The following psuedocode demonstrates the logic of the previous steps.
userStr = "date=YYYYMMDD&userid=123456"
sharedKey = "12345678901234567890123456789012345678901234567890123456789012345"
encUser = md5(sharedKey + userStr) + hex(userStr)

The following pseudocode demonstrates the same logic for PHP.


<?php
function bvEncodeUser($userID, $sharedkey) {
$userStr = 'date=' . date('Ymd') . '&userid=' . $userID;
return md5($sharedkey . $userStr) . bin2hex($userStr);
}
$encUser = bvEncodeUser("123456",
"12345678901234567890123456789012345678901234567890123456789012345");
?>

The final value of encUser represents the value of userToken that is used to integrate the body of the submission
page.
To obtain code examples that pertain to the generation of the encoded UAS for login integration, see "Example:
Integration Code."
Related Links
User authentication string options on page 74
Rendering the submission container page on page 27
Example: Integration code on page 75

Bazaarvoice Confidential

31

Bazaarvoice quick start implementation guide

Implementing Bazaarvoice SEO


Implementing SEO involves the following tasks.
Prerequisites
The following prerequisites must be satisfied before implementing SEO integration:
You must be using the Bazaarvoice JavaScript integration method.
You must provide an XML product feed to Bazaarvoice. See the Bazaarvoice data feeds guide for more
information.
Important!
If your UGC is displayed behind a tab, take note of the section that address this special case.

1. Create an automated process for daily tasks on page 32


2. Special case: When UGC is behind a tab on page 37
3. Verify your SEO implementation on page 39

Create an automated process for daily tasks


Create an automated process to perform the following tasks daily.
1. Download and unpack SEO files on page 32
2. Inject SEO content on product pages on page 33
3. Perform a string replacement within the SEO files on page 36
4. Handle the SEO URL parameter on page 36

Download and unpack SEO files


Every day the following files are made available on your production and staging FTP or SFTP accounts:

feeds/<ClientName>_smartseo.zip

feeds/<ClientName>_smartseo.zip.ready

Verify that the .ready file exists, then download the .zip file and extract its contents.
Note
The .ready file is created to notify you that the .zip is completely uploaded.

32

Bazaarvoice Confidential

Implementing Bazaarvoice SEO


The following table identifies the pages that are present if any content exists.
Type of UGC

Folder

Directory*

R&R

reviews

{DisplayCode}/reviews/product/1/001122.htm

Q&A

questions

{DisplayCode}/questions/product/1/112233.htm

OR
{DisplayCode}/questions/category/1/112233.htm

Campaigns

stories

{DisplayCode}/stories/category/1/stories/112233.htm

* In each directory, DisplayCode represents your unique display code, such as 1234-en_us.
Files in these directories are named SUBJECTID.htm, where SUBJECTID represents the URL-encoded ID of a product
or category. For example, a product that features reviews and has an ID of 00+1122, generates the following file
name:
{DisplayCode}/reviews/product/1/00%2B1122.htm

where DisplayCode represents your unique display code.


Note
Products and categories without UGC do not possess corresponding HTM files.
Because the SEO snapshot is refreshed daily while JavaScript-rendered content is updated throughout the
day, the two versions are not always synchronized perfectly. This difference between the versions is acceptable.
However, you must run the update every day to keep the versions reasonably synchronized. It is recommended
that you schedule your feed pickup after 11:00 a.m. CST, which is the time at which the feeds are typically
completed.

Inject SEO content on product pages


After you obtain and unzip the SEO files, insert them into your product and category pages.
For each page, embed the contents of the appropriate SEO file within the main content <div> element. For best
results, keep the contents of each SEO file intact and unchanged as they are injected.
Important!
The contents of each SEO file are UTF-8 encoded. If you use a different character set on your site, convert the file
to the appropriate encoding before inserting it into your page. Otherwise, special characters might not render
correctly.

Bazaarvoice Confidential

33

Bazaarvoice quick start implementation guide

Ratings and reviews


Depending on the nature of your implementation, one of the following <div> elements is likely to represent the
default main content for ratings and reviews:
For implementations that were completed before November, 2010:
<div id="BVReviewsContainer"></div>

For implementations that were completed after November, 2010:


<div id="BVRRContainer"></div>

The following example represents the content that must be added to this element on a product display page for
a product with an ID of 001122:
<div id="BVRRContainer">
<!-- include contents of {DisplayCode}/reviews/product/1/001122.htm if it exists -->
</div>

where DisplayCode represents your unique display code, such as 1234-en_us.


The ID of the <div> element can be customized. If you used the JavaScript API to change the ID, use the customized
<div> element.

Question and answer


The following <div> element represents the default main content for Q&A:
<div id="BVQAContainer"></div>

The following code represents the content that must be added to this element for a product with an ID of 001122:
<div id="BVQAContainer">
<!-- include contents of {DisplayCode}/questions/product/1/001122.htm if it exists -->
</div>

where DisplayCode represents your unique display code, such as 1234-en_us.


The ID of the <div> element can be customized. If you used the JavaScript API to change the ID, use the customized
<div> element.
For a category page with an ID of 112233, a similar change is made by using the following path:
{DisplayCode}/questions/category/1/112233.htm

where DisplayCode represents your unique display code.

34

Bazaarvoice Confidential

Implementing Bazaarvoice SEO

Campaigns
The following <div> element represents the default main content for campaigns:
<div id="BVSYContainer"></div>

The following code represents the content that must be added to this element for a product with an ID of 001122:
<div id="BVSYContainer">
<!-- include contents of {DisplayCode}/stories/product/1/stories/001122.htm
</div>

if it exists -->

where DisplayCode represents your unique display code, such as 1234-en_us.


The ID of the <div> element can be customized. If you used the JavaScript API to change the ID, use the customized
<div> element.
For a category page with an ID of 112233, a similar change is made by using the following path:
{DisplayCode}/stories/category/1/stories/112233.htm

where DisplayCode represents your unique display code.


Because campaign content supports different page types than reviews or questions, the path to campaign SEO
content contains a level that is absent from the paths for R&R and Q&A. If you choose to use a campaigns page
type other than show_stories by default, use the following table to identify the SEO file that you need to include
by default to match the JavaScript content.
$BV.UI Stories API Call

API Options

SEO File Name*

show_stories

subjectType: "category"

{DisplayCode}/stories/category/1/sto
ries/112233.htm

show_stories

subjectType: "product"

{DisplayCode}/stories/product/1/sto
ries/112233.htm

show_grid

subjectType: "category"

{DisplayCode}/stories/category/1/stories
grid/112233.htm

show_grid

subjectType : "product"

{DisplayCode}/stories/product/1/stories
grid/112233.htm

show_home

subjectType: "category"

{DisplayCode}/stories/category/1/storiessub
grid/112233.htm

show_home

subjectType: "all"

{DisplayCode}/stories/category/1/allstoriessub
grid/allstoriessubgrid.htm

* In each SEO file name, {DisplayCode} represents your unique display code. In each file name, 112233 represents
a sample category or product ID.

Bazaarvoice Confidential

35

Bazaarvoice quick start implementation guide

Perform a string replacement within the SEO files


When you enable the indexing of multiple pages, Bazaarvoice generates links to all additional pages of content.
However, the URLs contain a token that you must replace before they can function appropriately.
In the SEO files, the string INSERT_PAGE_URI represents this token, which is located wherever the current page's
URL must be inserted with either a question mark (?) or ampersand (&) at its end.
In R&R, the SEO file contains a value like the following example.
<a href="{INSERT_PAGE_URI}bvrrp={DisplayCode}/reviews/product/2/6789.htm">2</a>

where DisplayCode represents your unique display code, such as 1234-en_us.


If the URL of the current page is http://www.example.com/6789.htm, the link resembles the following example after
the string replacement:
<a href="http://www.example.com/6789.htm?bvrrp={DisplayCode}/reviews/product/2/6789.htm">2</a>

where DisplayCode represents your unique display code. In this example, the ? immediately precedes the bvrrp
parameter.
If the current page's URL already includes URL parameters, such as http://www.example.com/product.htm?id=6789,
the link resembles the following example after the string replacement:
<a href="http://www.example.com/product.htm?id=6789&bvrrp={DisplayCode}/reviews/prod
uct/2/6789.htm">2</a>

where DisplayCode represents your unique display code. In this example, the & immediately precedes the bvrrp
parameter.
Conduct this string-replacement operation whenever you include any SEO files on your page.

Handle the SEO URL parameter


Update your product and category pages to search for a new URL parameter that Bazaarvoice passes to them. The
value of this parameter indicates the path to the file that must be included in the SEO feed.
Complete this task separately for each Bazaarvoice content type. If you have implemented R&R as well as campaigns,
for example, you must use two additional URL parameters.
The following table identifies the default URL parameter that is associated with each Bazaarvoice product and
provides an example URL for a product with an ID of 6789.
Type of UGC

Default Parameter

Example Value*

Reviews

bvrrp

{DisplayCode}/reviews/product/2/6789.htm

Questions and answers

bvqap

{DisplayCode}/questions/product/2/6789.htm

Campaigns

bvsyp

{DisplayCode}/reviews/stories/2/sto
ries/6789.htm

36

Bazaarvoice Confidential

Implementing Bazaarvoice SEO


* In each example value, DisplayCode represents your unique display code, such as 1234-en_us.
These parameters exist in a URL only when it links to a page other than the first one. As a result, it is recommended
that you treat them as optional.
Contact the Support team at Bazaarvoice to change the name of a default parameter.
The logic that is associated with product and category pages does not always include the first page of content. As
a result, you must update this logic as follows to check for the value of the SEO URL parameter:
If the URL parameter exists and if the file to which its value refers exists in the SEO feed, include the contents
of that file instead of the default first page.
If the URL parameter does not exist or if the file to which it refers does not exist, use the default first page.
If a default first page does not exist, do not include any content.
The following pseudocode outlines this logic for ratings and reviews.
// returns the file that should be included on the product/category
// page or null if nothing should be included
function getRRSmartSEOFile() {
var SEOParam = getURLParameter('bvrrp');
var SEOFile = '/path/to/smartseo/' + SEOParam;
var defaultSEOFile = '/path/to/smartseo/{DisplayCode}/reviews/product/1/' +productID + '.htm';
if ( hasValue(SEOParam) && fileExists(SEOFile) ) {
return SEOFile;
} else if ( fileExists(defaultSEOFile) ){
return defaultSEOFile;
} else {
return null;
}
}

where DisplayCode represents your unique display code.


Leverage this logic when the appropriate Bazaarvoice content area is rendered, as the following example shows.
<div id="BVRRContainer">
{ if getRRSmartSEOFile() != null then insert
stringReplaceURLs(getRRSmartSEOFile()) }
</div>

Special case: When UGC is behind a tab


If your UGC resides behind a tab on your site, place the SEO content within a <div> element on your product pages.
Because tabbed navigation has become so common in recent years, search engines are capable of effectively
indexing content that resides behind a tab, provided the following two conditions are met:
1. The SEO content is present in the initial HTML format of the page and is not loaded through scripts on your
side.
2. The SEO content is visible on the page even after you turn off JavaScript in your browser and refresh the page.
Note
If the default state of the container that holds the SEO content is set to visibility: hidden or display: none, then:
Use JavaScript to set this property. Do not declare this property in a stylesheet or inline to the element.
Apply to all tabs so that all content is visible when the page is displayed with JavaScript off.

Bazaarvoice Confidential

37

Bazaarvoice quick start implementation guide


Example code:
Here is an example of the JavaScript code that can be used to hide tab content:
<script type="text/javascript">
document.getElementById('tab1').style.display
document.getElementById('tab2').style.display
document.getElementById('tab3').style.display
document.getElementById('tab4').style.display
</script>

=
=
=
=

'none';
'none';
'none';
'none';

Example product page:


Here is a link and image of our client's product page with UGC behind a tab: http://www.swansonvita
mins.com/NRN002/ItemDetail

38

Bazaarvoice Confidential

Implementing Bazaarvoice SEO

Verify your SEO implementation


Use the following checklist to verify that your SEO integration is implemented correctly.
Visually test the site to ensure that reviews or question- and answer-specific content does not appear
twice.
Ensure that the review dates within the JavaScript match the review dates within the SEO block. If a
review is approved on the same day on which the test is conducted, an acceptable difference of one
day might exist between the dates.
Open the page source for a page with SEO enabled, copy a portion of a review from the hosted
display, and attempt to locate that portion of the review in the page source. If the portion is visible
within the page source, SEO content is loaded into the page code and made available to search
engine crawlers.
Test that the SEO content is updating appropriately by rerunning the preceding tests at a later date
on a product or category that has received new content since the last tests were run. Ensure that the
new content is visible within the SEO block.
We highly recommend automating the download and server-side include of the SEO files. Test that
this will continue functioning as expected in the future and setup triggers if the download or include
fails.
View the page with JavaScript disabled and verify that the UGC is visible on the page.

Bazaarvoice Confidential

39

Bazaarvoice quick start implementation guide

Implementation checklists
This section contains checklists to help you verify that you have completed the steps necessary to implement a
Bazaarvoice product successfully.

General checklist
Use the following checklist to verify that your Bazaarvoice product or products are implemented correctly.
Make sure that the submission page URL has been sent to your Bazaarvoice IE. Include production and staging versions
of the URL.
If content is hidden behind a tab or other conditionally visible UI element on your product and category pages, make
sure that the steps in Displaying content that resides behind a tab on page 46 have been followed.
While not logged in to the system, test the submission link URLs first by specifying and then by not specifying a user. If
the login function is working properly, the submission link does not force a login attempt when you specify a user. For
more information, see Submission links on page 76.
Make sure that your product data feed with production data is being sent to Bazaarvoice's production FTP or SFTP
server. For more information, refer to the Bazaarvoice Product Feed document.
When launching to production, ensure that /bvstaging is removed from all Bazaarvoice URLs.

40

Bazaarvoice Confidential

Using advanced integration options

Using advanced integration options


The topics in this section describe how to implement and use the following optional features:
Login redirection with JavaScript
Displaying content that resides behind a tab
Targeted links
Sharing content through Facebook
Same-page submission
Event callbacks

Loading the API asynchronously


All Bazaarvoice content except the API loader file bvapi.js is loaded asynchronously. If you must load this content
asynchronously as well, do not include the bvapi.js script tag directly on your HTML pages. Instead, include one
of the following script blocks, depending on whether you use jQuery:
If you use jQuery, include the following block:
<script type="text/javascript">
var bvapiUrl = window.location.protocol + "//example.ugc.bazaarvoice.com/
bvstaging/static/1234/bvapi.js";
window.loadBazaarvoiceApi = function(callback) {
if (window.$BV) {
callback();
} else {
$.ajax({
url: bvapiUrl,
cache: true,
dataType: "script",
success: function() {
$($BV.docReady);
callback();
}
});
}
};
</script>

Bazaarvoice Confidential

41

Bazaarvoice quick start implementation guide


If you do not use jQuery, include the following JavaScript:
<script type="text/javascript">
(function() {
var bvapiUrl = window.location.protocol + "//example.ugc.bazaarvoice.com/
bvstaging/static/1234/bvapi.js";
function getScript(url, callback) {
var head = document.getElementsByTagName("head")[0] ||
document.documentElement,
script = document.createElement("script");
script.src = url;
script.type = "text/javascript";
script.charset = "utf-8";
script.setAttribute("async", "async");
script.onload = script.onreadystatechange = function () {
if (!this.readyState || this.readyState === "loaded" ||
this.readyState === "complete") {
script.onload = script.onreadystatechange = null;
callback();
}
};
head.insertBefore(script, head.firstChild);
}
//
//
//
//
//

work around Firefox 3.0, 3.5 lack of document.readyState


property.
Note: Because of this workaround, the <script> fragment must
be included within the <head> or <body> element so that it
executes before the window load event is fired.

var docReady, onDocReady = function(){docReady = true;};


if (document.readyState === undefined && document.addEventListener)
{
document.addEventListener("DOMContentLoaded", onDocReady,
false);
window.addEventListener("load", onDocReady, false);
}
window.loadBazaarvoiceApi = function(callback) {
if (window.$BV) {
callback();
} else {
getScript(bvapiUrl, function() {
if (docReady) {
$BV.docReady();
}
callback();
});
}
};
})();
</script>

All subsequent calls to Bazaarvoice API functions, such as $BV.ui(), are wrapped in loadBazaarvoiceApi calls, as
the following example shows:
loadBazaarvoiceApi(function() {
$BV.ui("rr", "show_reviews", { productId: "test1" });
});

Implementing inline ratings


Bazaarvoice recommends adding the following elements to pages that display multiple products in a list or grid,
such as category and search-results pages:
The product's overall rating
42

Bazaarvoice Confidential

Using advanced integration options


A star image that represents the overall rating
The number of reviews
Bazaarvoice provides two methods by which inline ratings can be implemented:
Ratings XML feed
Platform API (recommended approach)

Method comparison
Platform API

Ratings XML Data Feed

Level of development effort

Lower

Higher

Statistics freshness

Real-time updates

Updated only daily (potentially


out-of-sync with stats on product page)

Local repository of statistics for use in


other advanced areas (e.g., faceted
navigation, use in search results
algorithms, etc.)

No

Yes

Format

XML or JSON

XML only

Using the Bazaarvoice platform API for inline ratings


(recommended approach)
The Bazaarvoice platform API provides a highly optimized API method for retrieving review statistics such as average
rating. This method has been specifically built to handle high intensity applications such as search results pages
and product category listing pages.
For example, the platform API can be called for each desired product ID as a search results page is being rendered.
There is no requirement to cache these statistics locally prior to rendering the page. Additionally, Bazaarvoice can
host the star images for use in the application. There is no need to store a local copy of the star images. This method
gives you the flexibility to display the rating and images as you desire.
Note
Statistics returned by statistics.json/xml are global statistics calculated on the entire reviews set for a product
across all locales. If locale-specific statistics are required, contact your Implementation Engineer.

1. Request production and staging platform API keys for inline ratings use from your Implementation Engineer.
2. Use the appropriate product ID to call the platform API to request review statistics

Bazaarvoice Confidential

43

Bazaarvoice quick start implementation guide

Production:
http://example.ugc.bazaarvoice.com/data/statistics.json?apiversion=5.1&passkey=[api
key]&filter=productid:[product id]&stats=reviews

Staging:
http://example.ugc.bazaarvoice.com/bvstaging/data/statistics.json?apiver
sion=5.1&passkey=[api key]&filter=productid:[product id]&stats=reviews

The following URL shows a live example: http://reviews.apitestcustomer.bazaarvoice.com/bvstaging/da


ta/statistics.json?apiversion=5.1&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=productid:test1&stats=reviews
3. Map the overall ratings value (rounded to one decimal place) returned in the API response to link to the
appropriate BV-hosted star image URL.
Image URL pattern:
http://example.ugc.bazaarvoice.com/1234-en_us/[overall rating value]/[max rating:5]/rat
ing.gif

The following example retrieves the star image for 3.1 out of 5 stars:
http://example.ugc.bazaarvoice.com/1234-en_us/3_1/5/rating.gif

4. Utilize the API response and star image to display the inline rating image and overall rating value as needed
on your category or search listing page.

Using ratings XML feed for inline ratings


Bazaarvoice provides a ZIP file that contains a series of star image files. These images represent ratings values that
range from 0.0 through 5.0 and are incremented by tenths.
1. Store the images from the Bazaarvoice ZIP file on your webserver.
2. Download the Bazaarvoice ratings-only export feed and perform one of the following steps:
Store the feed on the webserver for direct referencing of the rating and review count.
Insert the overall rating and review count into your webstore database.
3. Use the appropriate product ID to look up the following values in the static file or local database:
Overall rating
Number of reviews
4. Map the overall rating value in the database to the appropriate star image file.
For example, if the overall rating value is 3.7, map it to the star image file named rating-3_7.gif.
For more information about ratings-only export feed, refer to Bazaarvoice Data Feeds.

44

Bazaarvoice Confidential

Using advanced integration options

Implementing login redirection with JavaScript


A client-side JavaScript option for login redirection can be implemented if the process of building the redirection
logic on the server side is too costly or not technically feasible. However, a client-side solution might briefly present
users with a blank page before redirecting them to the Login page. As a result, this solution might not provide the
most optimal user experience.
1. Place the following example code in the <head> section on every page that you want to display Bazaarvoice
content:
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
userToken: "XXXXX",
doLogin: function(successCallback, successUrl) {
window.location = "http://www.example.com/login.html?return=" +
encodeURIComponent(successUrl);
}
});
</script>

where XXXXX represents the Bazaarvoice-encoded UAS. For more information, see "Generating the User
Authentication String."
If an appropriate value is unavailable, leave this value blank.
2. Replace the value of doLogin with the function that is called when Bazaarvoice requires user authentication.
After a successful login attempt on a separate page, the user is redirected back to the value of successUrl. The
code in step 1 provides an example of redirecting to a login page that features a defined return URL.
Related Links
Generating the user authentication string on page 30
User authentication string options on page 74

Integrating with AJAX-type login methods


successCallback can be executed if an AJAX-type login method is used and the user is still on the submission

container page.

Bazaarvoice Confidential

45

Bazaarvoice quick start implementation guide

1. Place the following example code in the <head> section on every page that you want to display Bazaarvoice
content:
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>
<script type="text/javascript">
$BV.configure("global", {
userToken: "XXXXX",
doLogin: function(successCallback, successUrl) {
myExampleAjaxLogin(function myExampleAfterLogin(encoded_user_string) {
successCallback(encoded_user_string);
});
},
});
</script>

where the XXXXX represents the Bazaarvoice-encoded UAS.


If an appropriate value is unavailable, leave this value blank.
2. Replace the value of doLogin with the function that is called when Bazaarvoice requires user authentication.
3. After the user successfully logs in to the system, call successCallback and pass the UAS as the first parameter.
Related Links
Generating the user authentication string on page 30
User authentication string options on page 74

Displaying content that resides behind a tab


If Bazaarvoice content is hidden behind a tab or other conditionally visible UI element, implement a callback so
that the content can be displayed under the appropriate conditions, such as targeted links to a specific review,
question, answer, or campaign content.
To implement such a callback, define the doShowContent option in the appropriate show_*
by the following example code.

$BV.ui() call, as shown

<script type="text/javascript">
$BV.ui("rr", "show_reviews", {
productId: "XXXXX",
doShowContent: function() {
myExampleShowTab("#ReviewsTab");
}
});
</script>

Although the preceding example code pertains to a ratings and reviews integration, the manner in which doShow
Content specifies a function applies to all feature integrations.
When the primary content container needs to be visible, Bazaarvoice calls the function that is specified by
doShowContent. In the previous example, this function calls myExampleShowTab.
doShowContent supports asynchronous operations. A common need for such operations involves the inclusion of

functions from popular JavaScript libraries, such as jQuery. Additionally, the function can be configured with

46

Bazaarvoice Confidential

Using advanced integration options


callbacks to prevent the occurrence of actions that are based on content focusing. For example, returning a value
of false from doShowContent prevents it from scrolling to content, as the following code shows.
function doShowContent(application, displayCode, subject, deepLinkId, callback, source ) {
if ( I want to scroll ) {
myExampleAsyncShowTab('#exampleReviewsTab', { onFinish: callback });
return false;
}
else {
return false;
}
}

The following table identifies possible values for the source object.
If the value is...

Content focusing is called by...

readLink

A Read XXXX link

deepLink

A targeted URL

submission

Returning from the submission flow

Use these values to prevent specific content-focusing actions, depending on the events that trigger them.

Targeted link to Bazaarvoice content


Use targeted URLs to link directly to a specific review, question, answer, campaign, or other piece of content.
These URLs redirect to the applicable product or category page while setting a cookie that instructs the Bazaarvoice
integration on that page to display the appropriate content at the top of the main Bazaarvoice display area.
Ensure that the following prerequisites are satisfied before implementing this feature:
If the primary Bazaarvoice content resides behind a tab or depends on JavaScript running before it can be
made visible, define a JavaScript function for the doShowContent option. Otherwise, Bazaarvoice cannot
automatically open the tab that contains the targeted content.
The product feed must contain a valid product or category page URL for the corresponding product or category
ID in the targeted link. This URL allows Bazaarvoice to redirect users to the appropriate product or category
page. If a valid URL is not defined, you can specify a value explicitly as a parameter in the targeted link.

Example formats: Targeted URLs


The sections in this topic provide examples of targeted URLs. Regardless of the URL format that you use, ensure
that /bvstaging is removed from the URLs in your production environment.
Reviews
The following URL shows the format of a URL that deep links to a review.
http://reviews.example.com/bvstaging/1234-en_us/XXXXX/review/YYYYY/redirect.htm

In this example, XXXXX represents the product ID, and YYYYY represents the review ID.
Bazaarvoice Confidential

47

Bazaarvoice quick start implementation guide


Review comments
The following URL shows the format of a URL that deep links to a review comment.
http://reviews.example.com/bvstaging/1234-en_us/XXXXX/review/YYYYY/comment/ZZZZZ/redirect.htm

In this example, XXXXX represents the product ID, YYYYY represents the review ID, and ZZZZZ represents the review
comment ID.
Questions
The following URLs show the format of a URL that deep links to a question:

http://answers.example.com/bvstaging/answers/1234-en_us/product/XXXXX/question/YYYYY/redirect.htm

http://answers.example.com/bvstaging/answers/1234-en_us/category/XXXXX/question/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the question ID.
Answers
The following URLs show the format of a URL that deep links to an answer:

http://answers.example.com/bvstaging/answers/1234-en_us/product/XXXXX/answer/YYYYY/redirect.htm

http://answers.example.com/bvstaging/answers/1234-en_us/category/XXXXX/answer/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the answer ID.
Campaigns
The following URLs show the format of a URL that deep links to campaign content:

http://stories.example.com/bvstaging/stories/1234-en_us/product/XXXXX/story/YYYYY/redirect.htm

http://stories.example.com/bvstaging/stories/1234-en_us/category/XXXXX/story/YYYYY/redirect.htm

In these examples, XXXXX represents the product or category ID, and YYYYY represents the campaign content ID.
Campaign comments
The following URLs show the format of a URL that deep links to a comment on a piece of campaign content:

http://stories.example.com/bvstaging/stories/1234-en_us/product/XXXXX/story/YYYYY/com
ment/ZZZZZ/redirect.htm

http://stories.example.com/bvstaging/stories/1234-en_us/category/XXXXX/story/YYYYY/com
ment/ZZZZZ/redirect.htm

In these examples, XXXXX represents the product or category ID, YYYYY represents the campaign content ID, and
ZZZZZ represents the comment ID.

Overriding redirect URLs


If the URL that corresponds to the product or category page is not sent to Bazaarvoice or if an alternate URL is
desired, you can add the redirecturl parameter to explicitly define the URL to which Bazaarvoice redirects. If you

48

Bazaarvoice Confidential

Using advanced integration options


add the redirecturl parameter, the base domain of the redirect URL must match the base domain of the targeted
URL for security reasons.
The following URL provides an example override:
http://reviews.example.com/bvstaging/1234-en_us/pid123/review/4567/redirect.htm?redirec
turl=http%3A%2F%2Fwww.example.com%2Fpid123.html

Ensure that /bvstaging is removed from the URL before launching in your production environment.

Sharing content through Facebook


Implement Facebook sharing to allow your customers to bookmark content that they want to share with their social
networks.

Updating Facebook tags


Update your Facebook tags if you are implementing either the Facebook Like.
Facebook Like
Define the Facebook namespace if you have enabled either of the following options:
The Facebook Like button integration
Publishing to Facebook from the submission page
If one of these options is enabled but the Facebook namespace is not defined, Internet Explorer might behave in
an unreliable manner. Declare the fb namespace within the opening <html> element, as the following example
shows.
<html xmlns:fb="http://www.facebook.com/2008/fbml">

If other namespaces or attributes are already defined within the opening <html> element, leave them intact.
Social Buttons
Social buttons allows your customers to bookmark content that they want to share with their social networks.
Bookmarks appear in the Bazaarvoice-supported locations of your choice, as the following image shows.

Bazaarvoice Confidential

49

Bazaarvoice quick start implementation guide


When you share content with Facebook, the social-networking sites bots crawl your pages and search for titles,
descriptions, thumbnail images, and other information. Although the bots might estimate some of the values that
Facebook uses, you can use the following metadata tags to specify exact values:

<meta property="og:title" content="XXXXX" />

where XXXXX represents the title of the page.

<meta property="og:description" content="YYYYY" />

where YYYYY represents the description of the page.

<meta property="og:image" content="ZZZZZ" />

where ZZZZZ represents the URL that points to the image you want Facebook to use as the thumbnail.
For additional information, visit http://developers.facebook.com/docs/share.

Creating an application for Facebook


Bazaarvoice lets your customers publish submissions directly to their Facebook walls. To take advantage of this
feature, you must either create a new Facebook application (app) for Bazaarvoice to utilize or provide us with
access to an appropriate app that you already use.
Bazaarvoice requires the following information for the Facebook app that you plan to use:
App ID
API key
App secret, which is stored as an encrypted value
Additionally, the Facebook app must be configured to match the domain on which the submissions occur. Note
that if your staging environment (or any other non-production environment you wish to test against) has a different
domain than your production environment, you'll need to configure separate a Facebook app for each domain.
The following topics describe the process of creating a new Facebook app and help you identify the information
that Bazaarvoice requires for you to use an existing app.

Creating a new Facebook application


1. Use a standard Web browser and the administrator-level credentials that are associated with your Facebook
account to access http://www.facebook.com/developers.
The Developer page opens.
2. Click Set Up New App in the upper-right corner.
The Essential Information page opens.
3. Perform the following steps:
a) In the App Name text box, specify an app name that is relevant to your brand and meaningful to your
customers.
b) Click Agree to indicate that you agree to the Facebook terms and conditions.
50

Bazaarvoice Confidential

Using advanced integration options

c) Click Create App.


d) Optional: If you are asked to complete a CAPTCHA, specify the appropriate information and click
Submit.
The About page opens.
4. Upload a logo for Facebook to use.
5. In the navigation panel, click Web Site.
The Web Site page opens.
6. Perform the following steps on the Web Site page:
a) In the Site URL text box, specify the appropriate URL, which is typically your homepage, in the following
format:
http://www.example.com

b) In the Site Domain text box, specify the appropriate domain in the following format:
example.com

c) Click Save Changes.


The Summary page opens, displaying the application settings and any relevant usage statistics.
7. Send the values that correspond to the app ID, API key, and app secret to your Bazaarvoice engineer.

Using an existing Facebook application


1. 1. Use a standard Web browser and the administrator-level credentials that are associated with your Facebook
account to access http://www.facebook.com/developers.
Your existing Facebook apps are displayed on the Developer page.
2. Click the name of the appropriate app.
The app ID, API key, and app secret are displayed.
3. Send the values that correspond to the app ID, API key, and app secret to your Bazaarvoice engineer.
4. Confirm that the site URL corresponds to your homepage and that the site domain corresponds to the domain
on which Bazaarvoice submissions will occur.
If these values are set to other domains or URLs, you might want to create a new application for Bazaarvoice
to use.
5. Optional: To change these values, click Edit Settings and then click Web Site in the navigation panel.

Same-page submission
Same-page submission allows you to use a single page for both the display and submission of UGC.
The following topics describe the JavaScript functions that handle login duties, populate the submission <iframe>
element, and manage the page display:
AJAX-type login method

Bazaarvoice Confidential

51

Bazaarvoice quick start implementation guide


Separate login page
Same-page submission allows you to use a single page for both the display and submission of UGC. The following
topic describes the JavaScript functions that populate the submission <iframe> element and manage the page
display.
Example code is provided.

Implementing same-page submission with AJAX-type login


methods
Although Bazaarvoice supports same-page submission, additional configuration options must be defined to
account for all user interactions, including interactions that involve login integration. Even if same-page submission
is enabled, it is recommended that you build a standalone submission container to drive the submission of UGC
during email campaigns.
The following example code provides a stub of the code that must be implemented to support same-page submission
with an AJAX-type login method.
<script type="text/javascript">
$BV.configure("global", {
allowSamePageSubmission: true,
userToken: "XXXXX",
doLogin: function(successCallback, successUrl) {
myExampleAjaxLogin(function myExampleAfterLogin(encoded_user_string) {
successCallback(encoded_user_string);
});
},
doShowSubmission: function() {
myExampleShowLightbox("Submission_Lighbox");
},
onSubmissionReturn: function() {
myExampleCloseLightbox("Submission_Lighbox");
},
doScrollSubmission: function() {
myExampleScrollToSubmission();
return false;
}
});
</script>

Make the following changes to this code:


1. Replace the userToken value of XXXXX with the Bazaarvoice-encoded UAS.
If you do not have a value to place in this location, leave it blank.
2. Replace the value of doLogin with a function of your design.
Bazaarvoice calls this function when user authentication is required, provided the value of userToken is blank
or not set.
3. After a successful login attempt, call successCallback and pass the UAS as the first parameter.
4. Replace the value of doShowSubmission with a function of your design.
Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes
or to switch to the tab into which the submission form must load.
5. Replace the value of onSubmissionReturn with a function of your design.

52

Bazaarvoice Confidential

Using advanced integration options

Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes
or to switch away from the tab into which the submission form was loaded.
6. Replace the value of doScrollSubmission with a function of your design.
Bazaarvoice calls this function after the submission form is displayed/updated. This function can be used to
prevent the default scrolling behavior by returning false.
7. Place the following <div> element where you want the submission form to load on your product or category
page.
<div id="BVSubmissionContainer"></div>

Alternatively, to load the submission form into a different <div> element, such as the <div> in which the main
Bazaarvoice content loads, override the submission <div> name as shown by the following example for
ratings and reviews.
$BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

When this code is used in conjunction with the example $BV.configure, Write a Review links cause the
submission form to load in the location that displays the main block of reviews.
$BV.configure calls must be made prior to any $BV.ui calls that they affect.

Related Links
Implementing the submission container page on page 28
Generating the user authentication string on page 30
User authentication string options on page 74

Implementing same-page submission with a separate login page


To enable same-page submission but use it in conjunction with a separate login page, as opposed to an AJAX-type
login method, the following example code provides a stub of the code that must be implemented.
<script type="text/javascript">
$BV.configure("global", {
allowSamePageSubmission: true,
userToken: "XXXXX",
doLogin: function(successCallback, successUrl) {
window.location = "http://www.example.com/login.html?return=" +
encodeURIComponent(successUrl);
},
doShowSubmission: function() {
myExampleShowLightbox("Submission_Lighbox");
},
onSubmissionReturn: function() {
myExampleCloseLightbox("Submission_Lighbox");
},
doScrollSubmission: function() {
myExampleScrollToSubmission();
return false;
}
});
</script>

Make the following changes to this code:

Bazaarvoice Confidential

53

Bazaarvoice quick start implementation guide

1. Replace the userToken value of XXXXX with the Bazaarvoice-encoded UAS.


If you do not have a value to place in this location, leave it blank.
2. Replace the value of doLogin with a function of your design.
Bazaarvoice calls this function whenever user authentication is required. Ensure that the function redirects
the user to the login form.
3. After a successful login attempt on a separate page, redirect the user back to the value of successUrl.
4. Replace the value of doShowSubmission with a function of your design.
Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes
or to switch to the tab into which the submission form must load.
5. Replace the value of onSubmissionReturn with a function of your own design.
Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes
or to switch away from the tab into which the submission form was loaded.
onSubmissionReturn is called only when the user is not redirected to the login page prior to submission. If

the user is redirected, onSubmissionReturn is not called. Instead, the page is refreshed with the URL before
the user is redirected to the login page. Define submissionReturnUrl to override this URL.
6. Replace the value of doScrollSubmission with a function of your design.
Bazaarvoice calls this function after the submission form is displayed/updated. This function can be used to
prevent the default scrolling behavior by returning false.
7. Place the following <div> element where you want the submission form to load on your product or category
page.
<div id="BVSubmissionContainer"></div>

Alternatively, to load the submission form into a different <div> element, such as the <div> in which the main
Bazaarvoice content loads, override the submission <div> name as shown by the following example for
ratings and reviews.
$BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

When this code is used in conjunction with the example $BV.configure, Write a Review links cause the
submission form to load in the location that displays the main block of reviews.
$BV.configure calls must be made prior to any $BV.ui calls that they affect.

54

Bazaarvoice Confidential

Using advanced integration options


Related Links
Generating the user authentication string on page 30
User authentication string options on page 74

Implementing same-page submission


Although Bazaarvoice supports same-page submission, additional configuration options must be defined to
account for all user interactions. Even if same-page submission is enabled, it is recommended that you build a
standalone submission container to drive the submission of UGC during email campaigns.
The following example code provides a stub of the code that must be implemented to support same-page
submission.
<script type="text/javascript">
$BV.configure("global", {
allowSamePageSubmission: true,
doShowSubmission: function() {
myExampleShowLightbox("Submission_Lighbox");
},
onSubmissionReturn: function() {
myExampleCloseLightbox("Submission_Lighbox");
},
doScrollSubmission: function() {
myExampleScrollToSubmission();
return false;
}
});
</script>

Make the following changes to this code:


1. Replace the value of doShowSubmission with a function of your design.
Bazaarvoice calls this function before the submission form loads. This function can be used to show lightboxes
or to switch to the tab into which the submission form must load.
2. Replace the value of onSubmissionReturn with a function of your design.
Bazaarvoice calls this function after submission is completed. This function can be used to close lightboxes
or to switch away from the tab into which the submission form was loaded.
3. Replace the value of doScrollSubmission with a function of your design.
Bazaarvoice calls this function after the submission form is displayed/updated. This function can be used to
prevent the default scrolling behavior by returning false.
4. Place the following <div> element where you want the submission form to load on your product or category
page.
<div id="BVSubmissionContainer"></div>

Alternatively, to load the submission form into a different <div> element, such as the <div> in which the main
Bazaarvoice content loads, override the submission <div> name as shown by the following example for
ratings and reviews.
$BV.ui("rr", "show_reviews", {productId: "A1234", submissionContainerDiv: "BVRRContainer"});

Bazaarvoice Confidential

55

Bazaarvoice quick start implementation guide

When this code is used in conjunction with the example $BV.configure, Write a Review links cause the
submission form to load in the location that displays the main block of reviews.
$BV.configure calls must be made prior to any $BV.ui calls that they affect.

Related Links
Implementing the submission container page on page 28

Implementing ratings and reviews on your mobile


site
The mobile-optimized version of ratings and reviews is integrated with your existing mobile site. Visitors who
access your site by way of their JavaScript-enabled mobile devices can find it easier to view and contribute content.
If your business decides to render the mobile-optimized version of ratings and reviews, perform the following
steps to implement this feature:
1. Contact the Bazaarvoice Support team to start the implementation process.
2. Add the displayType configuration option to the global scope and set it to mobile, as the following example
code shows.
$BV.configure("global", {
...
displayType: "mobile",
...
});

Ensure that you add the displayType configuration option only to the display and submission pages that you
want to render as the mobile-optimized version of ratings and reviews. Do not set this option to mobile for
every display and submission page, as the non-mobile-optimized version of ratings and reviews must be
able to render on your non-mobile site.
3. You can use simple submission URLs to direct users to the mobile version of the review submission form. To
do so, set format query string parameter to a value of "mobilestandalone". Example: http://re
views.client.com/1234/productXYZ/writereview.htm?return=http%3A%2F%2Fwww.client.com%2Fproduc
tXYZ.html&format=mobilestandalone

Using the event callback


The Bazaarvoice JavaScript event callback enables you to track certain actions that occur with Bazaarvoice UI
components. For example, the event callback can be used to pass tracking information into your web analytics
system.

56

Bazaarvoice Confidential

Using advanced integration options


Common uses for the JavaScript event callback include the following examples:
Viewing the average rating and review count of a product while a user views the page. This information helps
to establish a relationship between the rating or review count and the conversion rate of a product.
Tracking the progress of a submission form and rates of abandonment.
Dynamically generating portions of a page based on information that the hooks provide, such as the current
phase of the submission process.

Example: Event callback


To use the event callback, specify the onEvent option when making $BV API calls, as the following example shows.
<script type="text/javascript">
$BV.ui("rr", "show_reviews", {
productId: "XXXXX",
onEvent: function(json) {
if (json.eventSource == "Action") {
myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
}
}
});
</script>

Event variables for ratings and reviews


The following table identifies the specific variables that are associated with the attributes variable in ratings and
reviews.
Variable

Value

Description

numReviews

Integer

Total number of approved reviews that are submitted on the product.

numRatingsOnlyReviews

Integer

Number of ratings-only reviews that are submitted on the product. By default,


a ratings-only review contains fewer than 50 characters of review text and
features no attached photos, videos, user-entered tags, or additional
user-entered fields.

percentRecommend

Integer (0-100)

Percentage of users who selected Yes as an answer to the question "Would


you recommend this product to a friend?"

avgRating

Float

Average rating of the product, expressed in a format that displays up to four


decimal places.

Bazaarvoice Confidential

57

Bazaarvoice quick start implementation guide


Example
<script type="text/javascript">
$BV.ui("rr", "show_reviews", {
productId: "XXXXX",
onEvent: function(json) {
alert(json.attributes.numReviews);
}
});
</script>

Event variables for question and answer


The following table identifies the specific variables that are associated with the attributes variable in question
and answer.
Variable

Value

Description

numQuestions

Integer Total number of approved questions that are submitted about the subject.

numAnswers

Integer Total number of approved answers that are submitted about the subject.

Example
<script type="text/javascript">
$BV.ui("qa", "show_questions", {
productId: "XXXXX",
subjectType: "product",
onEvent: function(json) {
alert(json.attributes.numQuestions);
}
});
</script>

Event variables for campaigns


In campaigns, the numStories variable is specifically associated with the attributes variable and identifies the
total number of approved campaign submissions for the corresponding product. The value of numStories can be
any integer.
Example
<script type="text/javascript">
$BV.ui("sy", "show_stories", {
productId: "XXXXX",
subjectType: "product",
onEvent: function(json) {
alert(json.attributes.numStories);
}
});
</script>

58

Bazaarvoice Confidential

Using advanced integration options

Event variables for all Bazaarvoice products


The following table identifies the specific variables that are associated with the attributes variable in all Bazaarvoice
products.
Variable

Value

Description

mediaType

String

Indicates that a visitor clicked hosted media within a piece of Bazaarvoice content. Possible values
are photo and video.

filterType

String

Indicates that a visitor clicked Filter By or Sort By and then selected a filter. Possible
values are as follows:
Date Newest First
Expert Reviews First
Photo Reviews First

Example
Update for current topic.
<script type="text/javascript">
$BV.ui("qa", "show_questions", {
productId: "XXXXX",
subjectType: "product",
onEvent: function(json) {
alert(json.attributes.numQuestions);
}
});
</script>

Additional event variables


The following table identifies some of the additional web analytics variables that pertain to common scenarios.
Variable

Values

Description

attributes

Specific to your Bazaarvoice


feature or features

See previous sections.

bvProduct

RatingsAndReviews

Current feature is ratings and reviews.

AskAndAnswer

Current feature is question and answer.

Stories

Current feature is campaigns.

Profiles

Current feature is profiles.

Bazaarvoice Confidential

59

Bazaarvoice quick start implementation guide

Variable

Values

Description

eType

Read

Content is available for the user to view.

Write

User is engaged with the content-submission process.

Support

User is engaged with additional submission processes, such


as providing feedback or reporting content as
inappropriate.

Display

JavaScript Event API was invoked by injection.

Action

JavaScript Event API was invoked by a user click or other


action.

Review

Action is being performed on a review.

Question

Action is being performed on a question.

Answer

Action is being performed on an answer.

Comment

Action is being performed on a comment.

Profile

Action is being performed on a profile.

Story

Action is being performed on a campaign item.

leafCategoryId

Alphanumeric

External ID of the category.

pageType (submission only)

Input

User is viewing the submission form.

Preview

User is viewing the Preview page.

Confirm

User is viewing the Thank You page or another end-result


page.

eventSource

eventTarget

60

Bazaarvoice Confidential

Using advanced integration options

Variable

Values

Description

pageStatus (submission only)

Cancelled

User cancelled the submission process.

AuthenticationFailure

Valid UAS was not passed to Bazaarvoice.

Expired

User's submission session expired.

AlreadySubmitted

User attempted to submit duplicate content soon after the


original submission.

Own

User attempted to submit helpfulness feedback for own


content.

Duplicate

User attempted to submit helpfulness feedback for content


for which he or she has already submitted feedback.

ValidationError

User attempted to submit content that does not pass


validation.

productId

Alphanumeric

External ID of the product.

rootCategoryId

Alphanumeric

External ID of the top-level category parent.

Variable

Values

Description

attributes

Specific to your Bazaarvoice


product or products

See previous sections.

bvProduct

RatingsAndReviews

Current product is ratings and reviews.

AskAndAnswer

Current product is question and answer.

Stories

Current product is campaigns.

Profiles

Current product is profiles.

Read

Content is available for the user to view.

Write

User is engaged with the content-submission process.

Support

User is engaged with additional submission processes, such


as providing feedback or reporting content as
inappropriate.

eType

Bazaarvoice Confidential

61

Bazaarvoice quick start implementation guide

Variable

Values

Description

eventSource

Display

JavaScript Event API was invoked by injection.

Action

JavaScript Event API was invoked by a user click or other


action.

Review

Action is being performed on a review.

Question

Action is being performed on a question.

Answer

Action is being performed on an answer.

Comment

Action is being performed on a comment.

Profile

Action is being performed on a profile.

Story

Action is being performed on a campaign item.

leafCategoryId

Alphanumeric

External ID of the category.

pageType (submission only)

Input

User is viewing the submission form.

Preview

User is viewing the Preview page.

Confirm

User is viewing the Thank You page or another end-result


page.

Cancelled

User cancelled the submission process.

Expired

User's submission session expired.

AlreadySubmitted

User attempted to submit duplicate content soon after the


original submission.

Own

User attempted to submit helpfulness feedback for own


content.

Duplicate

User attempted to submit helpfulness feedback for content


for which he or she has already submitted feedback.

ValidationError

User attempted to submit content that does not pass


validation.

productId

Alphanumeric

External ID of the product.

rootCategoryId

Alphanumeric

External ID of the top-level category parent.

eventTarget

pageStatus (submission only)

62

Bazaarvoice Confidential

Using advanced integration options


Contact your IPM to obtain a comprehensive list of web analytics variables.
Examples
The following code runs whenever each page of the submission process loads, such as the Edit, Preview, or
Submit page.
<script type="text/javascript">
$BV.ui("submission_container", {
onEvent: function(json) {
if ( json.eventSource == "Display" &&
(json.eType == "Write" || json.eType == "Support") ) {
alert("Submission step: " + json.pageType);
}
}
});
</script>

The following code runs whenever a user clicks a link or performs another action in ratings and reviews.
<script type="text/javascript">
$BV.ui("rr", "show_reviews", {
onEvent: function(json) {
if ( json.eventSource == "Action" ) {
alert("User click happened");
}
}
});
</script>

Bazaarvoice Confidential

63

Bazaarvoice quick start implementation guide

Appendix
The sections in this appendix provide information about the following topics:
Bazaarvoice JavaScript API
Submission links

JavaScript API details


All JavaScript API calls require the following Bazaarvoice JavaScript loader:
<script type="text/javascript"
src="//example.ugc.bazaarvoice.com/bvstaging/static/1234-en_us/bvapi.js">
</script>

The following types of calls are available after the loader is added:
Configuration calls
UI calls

Configuration calls
Make the following configuration call to set the default values for later UI calls:
$BV.configure(scope, config);

Each configuration call consists of the following parameters:

scope Identifies the degree to which the configuration options are applied, as specified by the following

values:

global Applies options to all future API calls.

rr Applies options to all future ratings and reviews API calls.

qa Applies options to all future question and answer API calls.

sy Applies options to all future campaigns API calls.

cp Applies options to all future profiles API calls.

config Simple JavaScript object that contains applicable configuration options or parameters.

The following code provides an example configuration call.


$BV.configure("global", {
userToken: "ABCDEF123456789ABCDEF123456789"
});

64

Bazaarvoice Confidential

Appendix
Related Links
Additional configuration options on page 71

UI calls
Make the following UI call to trigger an action or to load content:
$BV.ui(scope, method, config);

Each UI call consists of the following parameters:

scope Identifies the degree to which the configuration options are applied, as specified by the following

values:

rr Applies options to all future ratings and reviews API calls.

qa Applies options to all future question and answer API calls.

sy Applies options to all future campaigns API calls.

cp Applies options to all future profiles API calls.

method Specifies the action to take.

config Simple JavaScript object that contains applicable configuration options or parameters.

The following topics identify available methods as well as the required and optional configuration parameters with
which they are coupled.
Related Links
Additional configuration options on page 71

Ratings and reviews methods


The ratings and reviews methods correspond to the scope value of rr.

show_summary
The show_summary method loads content into the summary containers.
Required Parameter
productId

Optional Parameters
The optional parameters for show_summary are identical to the common parameters that are described in "Common
Display Options."
Example
$BV.ui("rr", "show_summary", {productId: "A1234"});

Bazaarvoice Confidential

65

Bazaarvoice quick start implementation guide


Related Links
Common display options on page 71

show_reviews
The show_reviews method loads content into the summary and content containers.
Required Parameter
productId

Optional Parameters
reviewId, page, num, sort, dir, sourceName, scrollToTop, suppressScroll, expandContextDataDimensionFilter,
expandBadgeGroupFilter, expandTagDimensionFilter, expandOverallRatingFilter, expandRatingDimensionFilter,
expandContentSourceFilter, commentId, showComments, hideComments, commentPage, commentNum, contextDataValues,
badges, tags, rating, ratings, contentSource, and all common parameters.

Example
$BV.ui("rr", "show_reviews", {productId: "A1234"});

submit_review
The submit_review method starts the process of submitting a review, such as when a user clicks Write a review.
Required Parameters
Either productId or chooseProduct.
Optional Parameters
The optional parameters for submit_review are identical to the common parameters.
Examples
$BV.ui("rr", "submit_review", {productId: "A1234"});

$BV.ui("rr", "submit_review", {chooseProduct: "true"});

submit_comment
The submit_comment method starts the process of submitting a review comment, such as when a user clicks Comment
on this review.
Required Parameters
productId and reviewId.

Optional Parameters
The optional parameters for submit_comment are identical to the common parameters.
Example
$BV.ui("rr", "submit_comment", {productId: "A1234"});

Question and answer methods


The question and answer methods correspond to the scope value of qa.

66

Bazaarvoice Confidential

Appendix

show_summary
The show_summary method loads content into the summary containers.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
The optional parameters for show_summary are identical to the common parameters that are described in "Common
Display Options."
Examples
$BV.ui("qa", "show_summary", {subjectType: "product", productId: "A1234"});

$BV.ui("qa", "show_summary", {subjectType: "category", categoryId: "B5"});

Related Links
Common display options on page 71

show_questions
The show_questions method loads content into the summary and content containers.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
page, num, sort, dir, expandQuestion, expandAnswer, scrollToTop, and all common parameters.

Examples
$BV.ui("qa", "show_questions", {subjectType: "product", productId: "A1234"});

$BV.ui("qa", "show_questions", {subjectType: "category", categoryId: "B5"});

show_search
The show_search method loads content into the summary and content containers with the question and answer
Search tab visible.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
search, searchPage, num, searchCategoryId, searchCategory, expandQuestion, expandAnswer, scrollToTop, and

all common parameters.


Examples
$BV.ui("qa", "show_search", {subjectType: "product", productId: "A1234"});

$BV.ui("qa", "show_search", {subjectType: "category", categoryId: "B5", search: "easy to use"});

Bazaarvoice Confidential

67

Bazaarvoice quick start implementation guide

submit_question
The submit_question method starts the process of submitting a question, such as when a user clicks Ask a question.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
The optional parameters for submit_question are identical to the common parameters.
Examples
$BV.ui("qa", "submit_question", {subjectType: "product", productId: "A1234"});

$BV.ui("qa", "submit_question", {subjectType: "category", categoryId: "B5"});

submit_answer
The submit_answer method starts the process of submitting an answer, such as when a user clicks Answer this
question.
Required Parameters
Either subjectType and productId or categoryId and questionId.
Optional Parameters
The optional parameters for submit_answer are identical to the common parameters.
Examples
$BV.ui("qa", "submit_answer", {subjectType: "product", productId: "A1234", questionId: 54321});

$BV.ui("qa", "submit_answer", {subjectType: "category", categoryId: "B5", questionId: 54321});

Campaigns methods
The campaigns methods correspond to the scope value of sy.

show_summary
The show_summary method loads content into the summary containers.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
The optional parameters for show_summary are identical to the common parameters that are described in "Common
Display Options."
Examples
$BV.ui("sy", "show_summary", {subjectType: "product", productId: "A1234"});

$BV.ui("sy", "show_summary", {subjectType: "category", categoryId: "B5"});

68

Bazaarvoice Confidential

Appendix
Related Links
Common display options on page 71

show_stories
The show_stories method loads content into the summary and content containers.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
storyId, page, num, sort, dir, scrollToTop, suppressScroll, expandContextDataDimensionFilter, expandBadge
GroupFilter, expandTagDimensionFilter, commentId, showComments, hideComments, commentPage, commentNum,
contextDataValues, badges, tags, and all common parameters.

Examples
$BV.ui("sy", "show_stories", {subjectType: "product", productId: "A1234"});

$BV.ui("sy", "show_stories", {subjectType: "category", categoryId: "B5"});

show_grid
The show_grid method loads the campaigns grid into the summary and content containers.
Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
page, sort, dir, scrollToTop, expandContextDataDimensionFilter, expandBadgeGroupFilter, expandTagDimension
Filter, contextDataValues, badges, tags, and all common parameters.

Examples
$BV.ui("sy", "show_grid", {subjectType: "product", productId: "A1234"});

$BV.ui("sy", "show_grid", {subjectType: "category", categoryId: "B5"});

show_home
The show_home method loads the All Content subject grid into the summary and content containers.
Optional Parameters
subjectType, categoryId, scrollToTop, and all common parameters.

Examples
$BV.ui("sy", "show_home", {subjectType: "all"});

$BV.ui("sy", "show_home", {subjectType: "category", categoryId: "B5"});

submit_story
The submit_story method starts the process of submitting content, such as when a user clicks Write content.

Bazaarvoice Confidential

69

Bazaarvoice quick start implementation guide


Required Parameters
subjectType, productId, or categoryId.

Optional Parameters
The optional parameters for submit_story are identical to the common parameters.
Examples
$BV.ui("sy", "submit_story", {subjectType: "product", productId: "A1234"});

$BV.ui("sy", "submit_story", {subjectType: "category", categoryId: "B5"});

submit_comment
The submit_comment method starts the process of submitting a comment, such as when a user clicks Comment on
this campaign content.
Required Parameters
Either subjectType and productId or categoryId and storyId.
Optional Parameters
The optional parameters for submit_comment are identical to the common parameters.
Examples
$BV.ui("sy", "submit_comment", {subjectType: "product", productId: "A1234", storyId: 54321});

$BV.ui("sy", "submit_comment", {subjectType: "category", categoryId: "B5", storyId: 54321});

Profiles methods
The profiles methods correspond to the scope value of cp.

show_profile
The show_profile method loads profiles content into the profile content containers.
Required Parameter
profileId

Optional Parameters
The optional parameters for show_profile are identical to the common parameters that are described in "Common
Display Options."
Example
$BV.ui("cp", "show_profile", {profileId: "sampleuser7890"});

70

Bazaarvoice Confidential

Appendix
Related Links
Common display options on page 71

submit_profile
The submit_profile method starts the process of editing or submitting a profile, such as when a user clicks Edit
my profile.
Optional Parameters
The optional parameters for submit_profile are identical to the common parameters.
Example
$BV.ui("cp", "submit_profile");

submission_container
The submission_container method does not include a scope parameter but can contain a config parameter.
Required Parameters
Unless anonymous submission is enabled, either doLogin or userToken is a required parameter for the submis
sion_container method.
Optional Parameters
The optional parameters for submission_container are identical to the submission parameters that are described
in Submission options on page 73.
Example
$BV.ui("submission_container", {userToken: "ABCDEF123456789ABCDEF123456789"});

Additional configuration options


The topics in this section provide information about the following types of configuration options:
Common display options
Submission options
Options that pertain to the UAS

Common display options


The following table identifies the configuration options that pertain to display pages and can be used in $BV.con
figure and $BV.ui API calls.
Option

Description

contentContainerDiv

ID or DOM element that identifies the <div> element associated with the main content.
The default value is BV<Product>Container.*

Bazaarvoice Confidential

71

Bazaarvoice quick start implementation guide

Option

Description

displayCode

Display code to use with the API call. The default value is the value that is used in the
bvapi.js URL.

doShowContent

Function that is called when Bazaarvoice needs to ensure the visibility of the <div>
element that is associated with the main content. For more information, see Displaying
content that resides behind a tab on page 46.

onEvent

Function that is called when Bazaarvoice events occur. For more information, see Ex
ample: Event callback on page 57.

secondarySummaryContainerDiv

ID or DOM element that identifies the <div> element associated with the secondary
summary content. The default value is BV<Product>SecondarySummaryContainer.*

submissionReturnUrl

URL to which one must link after a user completes a submission that was triggered by
a Bazaarvoice link on the page. The default value is the URL of the current page minus
the #anchors.

summaryContainerDiv

ID or DOM element that identifies the <div> element associated with the summary
content. The default value is BV<Product>SummaryContainer.*

submissionContainerUrl

URL to which a user is redirected for submission purposes; must contain the submission
integration code. The default value is specified in the Bazaarvoice configuration files.

* <Product> represents the relevant Bazaarvoice feature and is one of the following values:

RR ratings and reviews

QA question and answer

SY campaigns

CP profiles

Example
The following code provides an example of a $BV.configure call that utilizes these options.
<script type="text/javascript">
$BV.configure("rr", {
contentContainerDiv: "BVRRContainerCustom",
displayCode: "1234-en_us",
doShowContent: function() {
myExampleShowTab("Reviews");
},
onEvent: function(json) {
if (json.eventSource == "Action") {
myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
}
},
secondarySummaryContainerDiv: "BVRRSecondarySummaryContainerCustom",
submissionReturnUrl: "http://www.example.com/XXXXX.html",
summaryContainerDiv: "BVRRSummaryContainerCustom",
submissionContainerUrl: "http://www.example.com/submissionPage.html"
});
</script>

72

Bazaarvoice Confidential

Appendix

Submission options
The following table identifies the configuration options that pertain to submission pages and can be used in
$BV.configure and $BV.ui API calls.
Option

Description

allowSamePageSubmission

Allows submission to occur on a display page instead of on a separate, standalone


page. The default value is false.

canSetPageTitle

Controls whether the submission form sets the title of the page. The default value is
true.

doLogin

Function that is called when content is submitted but Bazaarvoice is not passed a
required value for userToken; useful for implementing an AJAX-type login method.
doLogin is passed the successCallback and successUrl parameters. Upon a

successful login attempt, either successCallback should be called, passing the


encoded user string as its first parameter, or the user should be redirected to suc
cessUrl.

doScrollSubmission

Function that is called every time Bazaarvoice updates the submission state; useful
if the default scrolling behavior must be customized. For example, doScrollSubmis
sion is called after the Edit page loads, on the Preview page, or if the edit page
reloads with errors.
To prevent the default scrolling behavior, this function must return false.

doShowSubmission

Function that is called before Bazaarvoice injects its submission form; useful if an
event must occur before the submission form appears, such as displaying a lightbox
that contains the form.

facebookXdChannelUrl

If the submission page allows for sharing content on Facebook, specify the URL of
the Facebook cross-domain communication channel as the value for this option. For
more information, see Sharing content through Facebook on page 49.

onEvent

Function that is called when Bazaarvoice events occur. For more information, see
Example: Event callback on page 57.

onSubmissionReturn

Function that is called at the end of the submission process; useful for closing
lightboxes or switching tabs after a submission is complete.

submissionContainerDiv

ID or DOM element that identifies the <div> element associated with the submission
form. The default value is BVSubmissionContainer.

submissionLoadingTimeout

Number of milliseconds to wait before displaying a Submission Currently Un


available message. The default value is 15000.

submissionSessionParameters

String that, if specified on the submission container page, is saved to the database
along with the submitted content.

Bazaarvoice Confidential

73

Bazaarvoice quick start implementation guide

Option

Description

submissionUnavailableMessage

String that is displayed if the submission form does not load before the
submission-loading timeout expires. The default value is Submission Currently
Unavailable.

userToken

The encoded UAS for the user who is currently logged in to the system. If this value
is unknown, leave it blank. For more information, see Generating the user authenti
cation string on page 30.

Example
The following code provides an example of a $BV.ui call that utilizes these options.
<script type="text/javascript">
$BV.ui("submission_container", {
allowSamePageSubmission: true,
canSetPageTitle: false,
doLogin: function(successCallback, successUrl) {
myExampleAjaxLogin(function myExampleAfterLogin(encoded_user_string) {
successCallback(encoded_user_string);
});
},
doShowSubmission: function() {
myExampleShowLightbox("Submission");
},
facebookXdChannelUrl: "/static/facebook_xd_receiver.htm",
onEvent: function(json) {
if (json.eventSource == "Action") {
myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
}
},
onSubmissionReturn: function() {
myExampleCloseLightbox("Submission");
},
submissionContainerDiv: "BVSubmissionContainerCustom",
submissionLoadingTimeout: 20000,
submissionSessionParameters: "custom text",
submissionUnavailableMessage: "We're sorry, submission is currently unavailable. Please
try again later.",
userToken: "XXXXX"
});
</script>

User authentication string options


The following table identifies the key-value pairs that can be included in a UAS.

74

Key

Description

Required

Requires Bazaarvoice To
Enable

affiliation

Automatically assigns an affiliation badge to the user. Contact


your Bazaarvoice IE for information about the values that are
supported for this key.

No

Yes

date

Today's date in the format YYYYMMDD or YYYY-MM-DD.

Yes

No

emailaddress

Supplies an email address to be associated with the user.

No

Yes

Bazaarvoice Confidential

Appendix

Key

Description

Required

maxage

Number of days before the UAS expires. The default number of no


days is 1. Increasing this value is useful in pre-authenticated URLs,

Requires Bazaarvoice To
Enable
No

such as the URLs that are used in email campaigns.


rank

Automatically assigns a rank badge to the user. Contact your


No
Bazaarvoice IE for information about the values that are supported
for this key.

Yes

subjectids

Identifies the product IDs used in verified purchaser badging. For Yes, if
one product, use the form subjectids=test1. For multiple
verified
purchaser
products, use the form subjectids=test1/test2/test3.
badging
enabled

No

userid

User's ID. Do not use email addresses.

Yes

No

username

Supplies the nickname to associate with the user.

Yes, if
enabled

Yes

verifiedpur

Indicates if the verified purchaser badging using on-the-fly simple Yes, if


submission is enabled. To enable, set value to true.
verified
purchaser
badging
enabled

chaser

No

Example: Integration code


To assist with your implementation, Bazaarvoice provides example code on GitHub for the following scenarios:
Generating the encoded UAS for login integration. Examples are available in the following languages:
C++
ASP.NET (C#)
ASP
Java
Implementing SEO for ratings and reviews. These examples can be adjusted for other Bazaarvoice products
and are available in the following languages:
PHP
ASP.NET (C#)
Java

Bazaarvoice Confidential

75

Bazaarvoice quick start implementation guide


Browse and download examples at https://github.com/bazaarvoice/HostedUIResources

Submission links
Bazaarvoice generates submission links as part of the hosted implementation. However, submission links can also
be generated outside that context, if necessary. For example, you might want to use submission links outside
Bazaarvoice-generated display components during the following scenarios:
Email campaigns that contain calls to action, such as encouraging customers to write reviews about products
that they purchased
Campaign pages that focus on driving UGC
Submission links within site navigation
Additional submission links outside the default Bazaarvoice components on your product and category pages
Submissions can be triggered either by the Bazaarvoice JavaScript API or by constructing an appropriate URL, as
the example formats in the following sections show.

Submission links for ratings and reviews


The following API call and URL format can be used to trigger the submission of a review:
By using the JavaScript API:
$BV.ui("rr", "submit_review", {productId: "XXXXX"});

where XXXXX represents the product ID.


By using a URL:
http://reviews.example.com/bvstaging/1234-en_us/XXXXX/writereview.htm?OPTIONS

where XXXXX represents the product ID and OPTIONS represents with the appropriate URL options.
Ensure that /bvstaging is removed from the example URL before launching within your production
environment.
Related Links
Options for submission link parameters on page 79

Submission links for question and answer


JavaScript API calls and URLs alike can trigger the submission of a question or an answer on either a product or
category page.

76

Bazaarvoice Confidential

Appendix
JavScript API calls
Make the following JavaScript API calls to trigger the submission of a question on a product or category page:
To trigger the submission of a question on a product page:
$BV.ui("qa", "submit_question", {subjectType: "product", productId: "XXXXX"});

where XXXXX represents the product ID.


To trigger the submission of a question on a category page:
$BV.ui("qa", "submit_question", {subjectType: "category", categoryId: "XXXXX"});

where XXXXX represents the category ID.


Similarly, you can make the following JavaScript API calls to trigger the submission of an answer on a product or
category page:
To trigger the submission of an answer on a product page:
$BV.ui("qa", "submit_answer", {subjectType: "product", productId: "XXXXX", questionId: YYYYY});

where XXXXX represents the product ID and YYYYY represents the ID of the question for which the answer is
submitted.
To trigger the submission of an answer on a category page:
$BV.ui("qa", "submit_answer", {subjectType: "category", categoryId: "XXXXX", questionId: YYYYY});

where XXXXX represents the category ID and YYYYY represents the ID of the question for which the answer is
submitted.
URL formats
Use the following URL formats to trigger the submission of a question on a product or category page:
To trigger the submission of a question on a product page:
http://answers.example.com/bvstaging/answers/1234-en_us/product/XXXXX/askquestion.htm?OPTIONS

where XXXXX represents the product ID and OPTIONS represents the appropriate URL options.
To trigger the submission of a question on a category page:
http://answers.example.com/bvstaging/answers/1234-en_us/category/XXXXX/askquestion.htm?OPTIONS

where XXXXX represents the category ID and OPTIONS represents the appropriate URL options.
Similarly, you can use the following URL formats to trigger the submission of an answer on a product or category
page:
To trigger the submission of an answer on a product page:
http://answers.example.com/bvstaging/answers/1234-en_us/product/XXXXX/question/YYYYY/answerques
tion.htm?OPTIONS

Bazaarvoice Confidential

77

Bazaarvoice quick start implementation guide


where XXXXX represents the product ID, YYYYY represents the ID of the question for which the answer is
submitted, and OPTIONS represents the appropriate URL options. For more information, see Options for sub
mission link parameters on page 79.
To trigger the submission of an answer on a category page:
http://answers.example.com/bvstaging/answers/1234-en_us/category/XXXXX/question/YYYYY/answerques
tion.htm?OPTIONS

where XXXXX represents the category ID, YYYYY represents the ID of the question for which the answer is
submitted, and OPTIONS represents the appropriate URL options.
Ensure that /bvstaging is removed from the URLs in your production environment.
Related Links
Options for submission link parameters on page 79

Submission links for campaigns


JavaScript API calls and URLs alike can trigger the submission of campaign content on a product or category page.
JavScript API calls
Make the following JavaScript API calls to trigger the submission of campaign content on a product or category
page:
To trigger the submission of campaign content on a product page:
$BV.ui("sy", "submit_story", {subjectType: "product", productId: "XXXXX"});

where XXXXX represents the product ID.


To trigger the submission of campaign content on a category page:
$BV.ui("sy", "submit_story", {subjectType: "category", categoryId: "XXXXX"});

where XXXXX represents the category ID.

URL formats
Use the following URL formats to trigger the submission of a campaign content on a product or category page:
To trigger the submission of campaign content on a product page:
http://stories.example.com/bvstaging/stories/1234-en_us/product/XXXXX/writestory.htm?OPTIONS

where XXXXX represents the product ID and OPTIONS represents the appropriate URL options.
To trigger the submission of a campaign content on a category page:
http://stories.example.com/bvstaging/stories/1234-en_us/category/XXXXX/writestory.htm?OPTIONS

where XXXXX represents the category ID and OPTIONS represents the appropriate URL options.

78

Bazaarvoice Confidential

Appendix
Ensure that /bvstaging is removed from the URLs in your production environment.
Related Links
Options for submission link parameters on page 79

Submission links for profiles


The following API call and URL format can be used to trigger the editing or submission of a profile:
By using the JavaScript API:
$BV.ui("cp", "submit_profile");

By using a URL:
http://ugc.example.com/bvstaging/profiles/1234-en_us/editprofile.htm?OPTIONS

Ensure that /bvstaging is removed from the URLs in your production environment.
The user ID is not part of the API or URL due to the following assumptions:
Users typically edit their own profiles.
The user ID is passed to Bazaarvoice as part of the authentication process.

Options for submission link parameters


The following table identifies URL parameters that can be appended to submission links to define or customize
behavior.
Option

Description

Suggested Use

campaignid

String of up to 255 characters that is recorded with submissions To determine the degree of success of a
that use this URL.
particular URL, such as one used in an
email campaign.

return

URL to direct users toward after submission is complete.

submissionurl

URL to use for the submission container page; must contain the To change the URL of the submission
Bazaarvoice integration code that is specified in Implementing container page to a value other than the
the submission container page on page 28. Users are redirected one that Bazaarvoice has configured.
to this URL to view the actual submission form. The default value
is the value of the URL that is configured in the Bazaarvoice
configuration files.

Bazaarvoice Confidential

Always define.

79

Bazaarvoice quick start implementation guide

Option

Description

Suggested Use

user

Use the encoded UAS with this submission.

When the user is known but not


necessarily logged in to the site, such as
during email campaigns. A maxage value
is typically defined for the UAS. For more
information, see Generating the user au
thentication string on page 30.

All values must be URL-encoded. The following URL provides an example submission link that uses the return and
campaignid parameter options.
http://reviews.example.com/bvstaging/1234-en_us/prod5678/writereview.htm?return=http%3A%2F%2Fexam
ple.com%2F&campaignid=PPE_EMAIL_OCT10

80

Bazaarvoice Confidential

3900 North Capital of Texas Highway


Suite 300, Austin, Texas 78746
Toll-Free: (866) 522-9227 | Phone: (512) 551-6000 | Fax: (512) 551-6001
www.bazaarvoice.com

Você também pode gostar