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.

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
}

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.

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://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 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.

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.

KeyDescriptionRequired
dateToday's date in the format YYYYMMDD or YYYY-MM-DD.Yes
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.No
useridUser's ID. Do not use email addresses.Yes
emailaddressEmail address.No

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 Example$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:

    Contact your Implementation Team for the Encoding Key
    

    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 = ""
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", "");
?>

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

To obtain code examples that pertain to the generation of the encoded UAS for login integration, see “Example: Integration Code.”