A container page is an HTML page hosted on the your website that will contain the submission form that Bazaarvoice uses to collect user-generated content.

Whenever a reviewer clicks a review submission link, Bazaarvoice redirects them to the submission container page (hosted on your website) while passing URL parameters that are required for the submission form to render.

Follow these steps to integrate the submission container page:

Note: How you implement your submission container page depends on if you're using site authentication or Bazaarvoice hosted authentication (recommended).

Refer to the user authentication topic for information about how to migrate from site authentication to hosted authentication.

The following instructions are for site authentication integration.

Step 1: Determine the login-redirection logic

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 the submission form to render.

Before you build the submission container page, ensure that the site 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
}

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. The following image illustrates the login-redirection logic.

Bazaarvoice

You are responsible for implementing the logic in the Client-controlled actions section of the chart.

Step 2: Create a submission form container page

You must create a submission container page to hold all Bazaarvoice content submissions.

  1. After the login-redirection logic is implemented, create a blank HTML submission container page and add the following example code within the head element of the submission container page that you created:

     <script type="text/javascript"
     src="http://default.ugc.bazaarvoice.com/bvstaging/static/1235-en_us/bvapi.js">
 </script>
 <script type="text/javascript">
     $BV.ui("submission_container", {
         userToken: "XXXXX"
     });
 </script>

    where XXXXX represents the encoded user athenticated string (UAS). If you do not have a value to place in this location, leave it blank.

  2. Place the following code within the body of the submission container page where you want the submission form to appear:

     <div id="BVSubmissionContainer"></div>

    The Bazaarvoice submission form is loaded within the BVSubmissionContainer div element.

Note: Use the URL of container page as the submissionContainerUrl when you integrate your user-generated content (UGC) into your product display pages.

Step 3: Generate the user authentication string (UAS)

If you are authenticating users, you must generate a user authentication string (UAS) so that Bazaarvoice can verify that the content came from a trusted source. UAS prevents third parties from fabricating or impersonating users.

Consisting of key-value pairs, a UAS is signed and encoded through the use of a shared key.

The following table identifies the ampersand-delimited keys and values that can be used in the string.

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 is useful in pre-authenticated URLs, such as the URLs that are used in email campaigns. No
userid User's ID. Do not use email addresses. Yes
emailaddress Email address. No

To enable verified purchaser badging using the simple submission method, you must add additional data to your user authentication string. The subjectids and verifiedpurchaser strings are necessary for the verified purchaser badge to display.

A pre-encoded string must be UTF-encoded, and its values must be URL-escaped. For example, the string Example$tring must be rendered as Example%24tring. The following code provides an example of a pre-encoded string.

date=2007-05-27&userid=ID12345

Refer to additional user authentication string options for more information.

Encode a user authentication string (example UAS)

Perform the following steps to encode a string:

  1. Generate the hex MD5 hash of the shared key, concatenated with the UAS. The resulting string is 32 characters long. Contact Bazaarvoice Support to request the shared encoding key from the implemention team.
  2. Hex encode the UAS.

  3. Concatenate the result of step 1 with the result of step 2.

    The following psuedocode demonstrates the logic for JavaScript.

    userStr = "date=YYYYMMDD&userid=123456"
sharedKey = ""
    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", "eXamP13");
?>

    The final value of encUser represents the value of userToken that is used to integrate the div of the submission page.

GitHub examples
Bazaarvoice provides example code on GitHub for generating the encoded UAS for login integration. Browse and download examples from https://github.com/bazaarvoice/HostedUIResources .

Examples are available in the following languages:

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

Decode a user authentication string (example UAS)

In this example the user is logged in and login is required; user=<encoded auth string> AND bvauthenticateuser=true

Example user authentication string:

http://reviews.client.com/1234/100018/ReviewSubmitFrame.htm?bvdisplaycode=1234&bvproductid=100018&bvpage=http%3A%2F%2Freviews.client.com%2F8867%2F100018%2Faction.htm%3Fformat%3Dembedded%26action%3DAddPositiveFeedback%26user%3D115f38671b90ce7fd289eaef0ec1bed1646174653d3230303930353035267573657269643d67617279return%3Dhttp%253A%252F%252Freviews.client.com%252F8867%252F100018%252Fsampleproduct.htm%26review%3D3972387%26campaignid%3DBV_NONE&bvcontenttype=REVIEW_SUBMISSION&bvauthenticateuser=true

To decode:

  • Strip off the first 32 characters from the user authentication string.
  • You’ll be left with this string 115f38671b90ce7fd289eaef0ec1bed1646174653d3230303930353035267573657269643d67617279.
  • This HEX decodes to date=20090505&userid=gary.
Note: The parameter maxage defaults to 1 if it wasn't included when the authentication string was encoded. Also it will not appear in the decode if it wasn’t part of the original encoding.
Note: Visit http://ostermiller.org/calc/encode.html to decode or encode a user authentication string (UAS).