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"});

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 Client Care 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 Client Care 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

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.

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.