Appendix API methods

Refer to the following API methods for additional information:

JavaScript API details

To display Ratings & Reviews or Questions & Answers content on your product display pages (PDP), you must add the Bazaarvoice JavaScript API to your website.

To integrate the JavaScript API, complete the following steps on every page that will display Bazaarvoice content.

<script type="text/javascript"
    src="//default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
</script>

The following types of calls are available after the API 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 & Reviews API calls.
- qa—Applies options to all future Questions & Answers 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"
});

UI calls

Make the following UI call to trigger an action or 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 Questions and Answers 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.

Ratings & Reviews API methods

The Ratings & Reviews methods correspond to the scope value of rr.

show_summary

The show_summary method loads content into the summary containers.

Required parameter	Optional parameters	Example
`productId`	The optional parameters for `show_summary` are identical to the parameters described in common display configuration options.	`$BV.ui("rr", "show_summary", {productId: "A1234"});`

show_reviews

The show_reviews method loads content into the summary and content containers.

Required parameter	Optional parameters	Example
`productId`	`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`	`$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 the “Write a review” link.

Required parameter	Optional parameters	Example
Either `productId` or `chooseProduct`	The optional parameters for submit_review are identical to the parameters described in common display configuration options.	`$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 the “Comment on this review” link.

Required parameter	Optional parameters	Example
Either `productId` or `reviewID`	The optional parameters for `submit_comment` are identical to the parameters described in common display configuration options.	`$BV.ui("rr", "submit_comment", {productId: "A1234"});`

Questions & Answers API methods

The Questions & Answers methods correspond to the scope value of qa.

show_summary

The show_summary method loads content into the summary containers.

Required parameters	Optional parameters	Example
`subjectTypeproductIdcategoryId`	The optional parameters for `show_summary` are identical to the parameters described in common display configuration options.	`$BV.ui("qa", "show_summary", {subjectType: "product", productId: "A1234"});` `$BV.ui("qa", "show_summary", {subjectType: "category", categoryId: "B5"});`

show_questions

The show_questions method loads content into the summary and content containers.

Required parameters	Optional parameters	Example
`subjectTypeproductIdcategoryId`	`page, num, sort, dir, expandQuestion, expandAnswer, scrollToTop`	`$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 questions and answers Search tab visible.

Required parameters	Optional parameters	Example
`subjectTypeproductIdcategoryId`	`psearch, searchPage, num, searchCategoryId, searchCategory, expandQuestion, expandAnswer, scrollToTop`	`$BV.ui("qa", "show_search", {subjectType: "product", productId: "A1234"});` `$BV.ui("qa", "show_search", {subjectType: "category", categoryId: "B5", search: "easy to use"});`

submit_question

The submit_question method starts the process of submitting a question, such as when a user clicks “Ask a question”.

Required parameters	Optional parameters	Example
`subjectTypeproductIdcategoryId`	The optional parameters for `submit_question` are identical to the parameters described in common display configuration options	`$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 the “Answer this question” link.

Required parameters	Optional parameters	Example
`subjectTypeproductIdcategoryId` and `questionId`	The optional parameters for `submit_answer` are identical to the parameters described in common display configuration options	`$BV.ui("qa", "submit_answer", {subjectType: "product", productId: "A1234", questionId: 54321});` `$BV.ui("qa", "submit_answer", {subjectType: "category", categoryId: "B5", questionId: 54321});`

Submission container API method

The submission_container method does not include a scope parameter but can contain a config parameter.

Required parameter	Optional parameters	Example
Either `suserToken` or `submission_container` is required unless anonymous submission is enabled.	The optional parameters for `submission_container` are identical to the submission parameters that are described in submission configuration options.	`$BV.ui("submission_container", {userToken: "ABCDEF123456789ABCDEF123456789"});`

Common display configuration options

The following table identifies the configuration options that apply to display pages and can be used in $BV.configure 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`.*
`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 called when Bazaarvoice needs to ensure the visibility of the `<div>` element that is associated with the main content. Refer to displaying content that resides behind a tab for more information.
`onEvent`	Function called when Bazaarvoice events occur. Refer to example event callback for more information.
`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 the consumer is directed to after they complete a review submission. It is 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. It must contain the submission integration code. The default value is specified in the Bazaarvoice configuration files.

* <Product> represents the relevant Bazaarvoice feature and can be replaced with one of these values:

RR – ratings and reviews
QA – question and answer

Example

The following code provides an example of a $BV.configure call that uses these options.

<script type="text/javascript">
    $BV.configure("rr", {
        contentContainerDiv: "BVRRContainerCustom",
        displayCode: "1235-en_us",
        doShowContent: function() { 
            myExampleShowTab("Reviews"); 
        },
        onEvent: function(json) { 
            if (json.eventSource == "Action") {
                myExampleAnalyticsTrackEvent("Bazaarvoice interaction happened");
            }
        },
        secondarySummaryContainerDiv: "BVRRSecondarySummaryContainerCustom",
        submissionReturnUrl: "http://www.client.com/XXXXX.html",
        summaryContainerDiv: "BVRRSummaryContainerCustom",
        submissionContainerUrl: "http://www.client.com/submissionPage.html"
    });
</script>

Submission configuration options

The following table identifies the configuration options that apply 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 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 called when content is submitted but Bazaarvoice is not passed a required value for `userToken`. It is 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 `successUrl`.
`doScrollSubmission`	Function called every time Bazaarvoice updates the submission state; useful if the default scrolling behavior must be customized. For example, `doScrollSubmission` 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 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.
`onEvent`	Function called when Bazaarvoice events occur. Refer to example event callback for more information.
`onSubmissionReturn`	Function 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 Unavailable` 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.
`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. Refer to generating the user authentication string (UAS) for more information.

Example

The following code provides an example of a $BV.ui call that uses 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 configuration options

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

Key	Description	Required	Requires Bazaarvoice To Enable
`affiliation`	Automatically assigns an affiliation badge to the user. Contact Bazaarvoice Support 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
`maxage`	Number of days before the UAS expires. The default number of days is `1`. Increasing this value is useful in pre-authenticated URLs, such as those used in email campaigns.	no	No
`rank`	Automatically assigns a rank badge to the user. Contact Bazaarvoice Support for information about the values that are supported for this key.	No	Yes
`subjectids`	Identifies the product IDs used in verified purchaser badging. For one product, use the form `subjectids=test1`. For multiple products, use the form `subjectids=test1/test2/test3`.	Yes, if verified purchaser 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
`verifiedpurchaser`	Indicates if the verified purchaser badging using on-the-fly simple submission is enabled. To enable, set value to `true`.	Yes, if verified purchaser badging enabled	No

Example UAS integration code (GitHub)

To assist with your implementation, Bazaarvoice provides example code on GitHub for generating the encoded UAS for login integration.

Examples are available in the following languages:

C++
ASP.NET (C#)
ASP
Java

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

Submission links

Bazaarvoice generates simple submission links (ssURLs) as part of hosted user authentication. A simple submission URL (ssURL) quickly takes customers to a review submission form without having them go through a lengthy sign-in process.

However, you might want to use submission links outside the context of Bazaarvoice-hosted submission forms, during the following scenarios:

Email campaigns that contain calls to action, such as links to “Write a review” about a product they’ve recently purchased
Campaign pages that focus on driving user-generated content
Submission links within website navigation

Review submissions can be triggered by the Bazaarvoice JavaScript API or by constructing an appropriate ssURL, as the following example formats show.

Note: Refer to simple submission URLs for more information.

Ratings & Reviews submissions (API or URL)

Use the following API call or URL format to trigger the submission of a review:

By using the JavaScript API:
```
$BV.ui("rr", "submit_review", {productId: "XXXXX"});
```
XXXXX represents the product ID.
By using a URL:

http://reviews.client.com/bvstaging/1235-en_us/XXXXX/writereview.htm?OPTIONS

XXXXX represents the product ID and OPTIONS represents the appropriate URL options.

Note: JavaScript API calls and URLs can also trigger the submission of a question or an answer on product page.

Question submissions (API or URL)

Use the following API call or URL format to trigger the submission of a question on a product or category page:

By using the JavaScript API:
- To trigger the submission of a question on a product page:
```
$BV.ui("qa", "submit_question", {subjectType: "product", productId: "XXXXX"});
```
  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"});
```
  XXXXX represents the category ID.
By using a URL:
- To trigger the submission of a question on a product page:
  
  http://answers.client.com/bvstaging/answers/1235-en_us/product/XXXXX/askquestion.htm?OPTIONS
  
  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.client.com/bvstaging/answers/1235-en_us/category/XXXXX/askquestion.htm?OPTIONS
  
  XXXXX represents the category ID and OPTIONS represents the appropriate URL options.

Answer submissions (API or URL)

Use the following JavaScript API calls or URL format to trigger the submission of an answer on a product or category page:

By using the JavaScript API:
- To trigger the submission of an answer on a product page:
```
$BV.ui("qa", "submit_answer", {subjectType: "product", productId: "XXXXX", questionId: YYYYY});
```
  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});
```
  XXXXX represents the category ID and YYYYY represents the ID of the question for which the answer is submitted.
By using a URL:
- To trigger the submission of an answer on a product page:
  
  http://answers.client.com/bvstaging/answers/1235-en_us/product/XXXXX/question/YYYYY/answerquestion.htm?OPTIONS
  
  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. Refer to additional submission link parameters for more information.
- To trigger the submission of an answer on a category page:
  
  http://answers.client.com/bvstaging/answers/1235-en_us/category/XXXXX/question/YYYYY/answerquestion.htm?OPTIONS
  
  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.

Additional 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 that use this URL.	To determine the degree of success of a particular URL, such as one used in an email campaign.
`return`	URL to direct users toward after submission is complete.	Always define.
`submissionurl`	URL to use for the submission container page. It must contain the Bazaarvoice integration code that is specified in implementing the submission container page. Users are redirected 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.	To change the URL of the submission container page to a value other than the one that Bazaarvoice has configured.
`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. Refer to generating the user authentication string (UAS) for more information.

Pop out

Ratings & Reviews legacy (PRR)

Technical setup

Product feeds

Collect content

Display content

Optimizing content (SEO)

Integrate analytics

View insights

Create reports

Design services and offerings

Learn more

Appendix API methods

JavaScript API details

Configuration calls

UI calls

Ratings & Reviews API methods

show_summary

show_reviews

submit_review

submit_comment

Questions & Answers API methods

show_summary

show_questions

show_search

submit_question

submit_answer

Submission container API method

Common display configuration options

Example

Submission configuration options

Example

User authentication string configuration options

Example UAS integration code (GitHub)

Submission links

Ratings & Reviews submissions (API or URL)

Question submissions (API or URL)

Answer submissions (API or URL)

Additional submission link parameters

Select your language:

Pop out

Ratings & Reviews legacy (PRR)

Technical setup

Product feeds

Collect content

Display content

Optimizing content (SEO)

Integrate analytics

View insights

Create reports

Design services and offerings

Learn more

JavaScript API details

Configuration calls

UI calls

Ratings & Reviews API methods

show_summary

show_reviews

submit_review

submit_comment

Questions & Answers API methods

show_summary

show_questions

show_search

submit_question

submit_answer

Submission container API method

Common display configuration options

Example

Submission configuration options

Example

User authentication string configuration options

Example UAS integration code (GitHub)

Submission links

Ratings & Reviews submissions (API or URL)

Question submissions (API or URL)

Answer submissions (API or URL)

Additional submission link parameters

Support

Feedback

Language

Print

Toggle dropdowns

Remove highlights