JavaScript API details

All JavaScript API calls require the following Bazaarvoice JavaScript loader:

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

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.

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

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

Questions & Answers methods

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

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

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

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

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

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, expandBadgeGroupFilter, 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, expandTagDimensionFilter, 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.

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

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 submission_container method.

Optional Parameters

The optional parameters for submission_container are identical to the submission parameters that are described in Submission options.

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.configure and $BV.ui API calls.

OptionDescription
contentContainerDivID or DOM element that identifies the <div> element associated with the main content. The default value is BV<Product>Container.*
displayCodeDisplay code to use with the API call. The default value is the value that is used in the bvapi.js URL.
doShowContentFunction 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.
onEventFunction that is called when Bazaarvoice events occur. For more information, see Example: Event callback.
secondarySummaryContainerDivID or DOM element that identifies the <div> element associated with the secondary summary content. The default value is BV<Product>SecondarySummaryContainer.*
submissionReturnUrlURL 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.
summaryContainerDivID or DOM element that identifies the <div> element associated with the summary content. The default value is BV<Product>SummaryContainer.*
submissionContainerUrlURL 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: "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 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.

OptionDescription
allowSamePageSubmissionAllows submission to occur on a display page instead of on a separate, standalone page. The default value is false.
canSetPageTitleControls whether the submission form sets the title of the page. The default value is true.
doLoginFunction 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 successUrl.

doScrollSubmissionFunction that is 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.

doShowSubmissionFunction 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.
facebookXdChannelUrlIf 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.
onEventFunction that is called when Bazaarvoice events occur. For more information, see Example: Event callback.
onSubmissionReturnFunction that is called at the end of the submission process; useful for closing lightboxes or switching tabs after a submission is complete.
submissionContainerDivID or DOM element that identifies the <div> element associated with the submission form. The default value is BVSubmissionContainer.
submissionLoadingTimeoutNumber of milliseconds to wait before displaying a Submission Currently Unavailable message. The default value is 15000.
submissionSessionParametersString that, if specified on the submission container page, is saved to the database along with the submitted content.
submissionUnavailableMessageString that is displayed if the submission form does not load before the submission-loading timeout expires. The default value is Submission Currently Unavailable.
userTokenThe 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 authentication string.

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.

KeyDescriptionRequiredRequires Bazaarvoice To Enable
affiliationAutomatically assigns an affiliation badge to the user. Contact your Bazaarvoice IE for information about the values that are supported for this key.NoYes
dateToday's date in the format YYYYMMDD or YYYY-MM-DD.YesNo
emailaddressSupplies an email address to be associated with the user.NoYes
maxageNumber of days before the UAS expires. The default number of days is 1. Increasing this value is useful in pre-authenticated URLs, such as the URLs that are used in email campaigns.noNo
rankAutomatically assigns a rank badge to the user. Contact your Bazaarvoice IE for information about the values that are supported for this key.NoYes
subjectidsIdentifies 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 enabledNo
useridUser's ID. Do not use email addresses.YesNo
usernameSupplies the nickname to associate with the user.Yes, if enabledYes
verifiedpurchaserIndicates if the verified purchaser badging using on-the-fly simple submission is enabled. To enable, set value to true.Yes, if verified purchaser badging enabledNo

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

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

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.

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.client.com/bvstaging/1235-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.

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

JavaScript 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.client.com/bvstaging/answers/1235-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.client.com/bvstaging/answers/1235-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.client.com/bvstaging/answers/1235-en_us/product/XXXXX/question/YYYYY/answerquestion.htm?OPTIONS

    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 submission link parameters.

  • 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

    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.

JavaScript API calls and URLs alike can 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://Default/bvstaging/stories/1235-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://Default/bvstaging/stories/1235-en_us/category/XXXXX/writestory.htm?OPTIONS

    where XXXXX represents the category ID 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.

OptionDescriptionSuggested Use
campaignidString 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.
returnURL to direct users toward after submission is complete.Always define.
submissionurlURL to use for the submission container page; 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.
userUse 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 authentication string.

All values must be URL-encoded. The following URL provides an example submission link that uses the return and campaignid parameter options.

http://reviews.client.com/bvstaging/1235-en_us/prod5678/writereview.htm?return=http%3A%2F%2Fclient.com%2F&campaignid=PPE_EMAIL_OCT10