Authentication is the process of confirming a user’s identity, and it provides a way to ensure that legitimate users create content on your site. Through authentication, Bazaarvoice can confirm a user’s email address and link the email address to a profile in the Bazaarvoice network. (Authentication is not how fraud is detected; that’s authenticity.)

Note: Hosted authentication is the recommended method of authentication. Site authentication significantly decreases the volume of user submissions, and it requires that your technical team perform additional integration work to tie Conversations to your site’s login process. Use site authentication only if you have a legal or business requirement that necessitates that your customers log in to Conversations.

Site authentication requires users to log in to your site’s authentication system. Before users can submit product reviews, questions, or answers, they must log in with the same credentials they used to access your site. Use this method only if you have a legal or business requirement that necessitates that your customers log in to Conversations.

Here is the workflow of hosted and site authentication:

Hosted Authentication Site Authentication

Integrate with Conversations

To successfully integrate with Conversations and require site authentication, you must perform these tasks.

Step 1: Enable and configure site authentication

Complete the following steps to set up site authentication in Conversations:

  1. Log in to the Bazaarvoice Workbench and then click Settings » Manage Applications. The Site Manager page is displayed.
  2. From the Implementations list, edit the implementation in which you want to enable site authentication.
  3. In the Settings section of the configuration hub, click User authentication.
  4. At the top of the User Authentication page, click the Site Authentication Integration tab to display the Authentication Integration page.
  5. Enable the Require site authentication option.
  6. Determine whether you want to enable the Inject Nickname Data option. Refer to Inject data using site authentication for information about injecting nickname data.
  7. Use the Provide email address on submission options to specify whether an email address is required, optional, or not requested when users submit reviews, comments, questions, or answers:
    • Required—An email address is required for submissions. This is the default option.
    • Optional—An email address is optional for submissions.
    • Not Requested—The email address is excluded from submission forms.
  8. Enter a web address (URL) for Staging site login URL. Test users on your staging site will be redirected to log in here before writing content.
  9. Enter a web address (URL) for Production site login URL. Users on your production site will be redirected to log in here before writing content.

Step 2: Host a container page and reference its URL from Conversations

The container page facilitates site authentication redirects.

Create the container page on the same domain where Conversations is integrated. Typically, this is the domain from which your product pages are served. If your implementation uses bv.js, it should contain the following content:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8"/>
    <title></title>
    <meta name="robots" content="noindex, nofollow">
    <link rel="canonical" href="container.htm"/>
    <meta name="bv:pageType" content="container">
  </head>
  <body>
    <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/<environment>/<locale>/bv.js"></script>
  </body>
</html>

Note: If your existing implementation uses the scout file (bvapi.js), your HTML document should look similar to the following:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8"/>
    <title></title>
    <meta name="robots" content="noindex, nofollow">
    <link rel="canonical" href="container.htm"/>
  </head>
  <body>
    <script type="text/javascript" src="https://display.ugc.bazaarvoice.com/bvstaging/static/<client_name>/<site_ID>/<locale>/bvapi.js"></script>
    <script>
      $BV.container('global', {} );
    </script>
  </body>
</html>

Replace container.htm with the relative path to the canonical URL of this page, and replace <client_name>, <site_ID>, <environment>, and <locale> with your values.

Note: A canonical URL contains metadata about the page. The metadata points search engines to the official address of a page. For example, if you do not want search engines to treat https://url.com?page=1 and https://url.com?page=2 as different pages, provide an absolute link, such as <link rel="canonical" href="https://url.com">, to instruct search engines to point both URLs to https://url.com.

After creating the container page, you must enter its URL in Conversations by doing the following:

  1. In the configuration hub, go to Technical Setup » Site Profile.
  2. Enter the container page URL in Container URL.
  3. In the configuration hub, go to Settings » User Authentication.
  4. Click the Site Authentication Integration tab.
  5. Enter the staging site login URL in Staging site login URL.
  6. Enter the production site login URL in Production site login URL.

Step 3: Generate a user authentication string (UAS)

A user authentication string (UAS) consists of key-value pairs that are hashed and encoded (but not encrypted). This string enables Bazaarvoice to verify that it comes from a trusted source, thereby preventing third parties from fabricating or impersonating users. You can use a UAS, for example, to inject data into a review submission form if your implementation uses site authentication.

Note: A UAS must be created server-side to maintain the secrecy of the shared key.

Follow these steps to create a UAS that can be used in data injection:

  1. Determine the key-value pairs to include in the UAS, which must be delimited in the string by ampersands (&). Here are the supported keys:
    Key Description Required
    date Today's date, in the format YYYYMMDD or YYYY-MM-DD. Yes
    userid

    Consumer's user ID. Do not use an email address for this value.

    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
    verifiedpurchaser Whether the user is verified to have purchased one or more products (True). Omit this parameter or set it to False if the user is not a verified purchaser. No
    subjectids A list of product external IDs that the user is verified to have purchased, thereby ensuring that the verifiedpurchaser key cannot be applied to other products. If you specify multiple IDs, separate them using a slash (/). No
    Age Age range without spaces. For example: 35to44 or 65orOver. No
    Gender The user's gender (Male or Female). No
    emailaddress Contributor's email address. This value must be URL-encoded. No
    IncentivizedReview Whether the contributor received a free product or service to review (True). Omit this parameter or set it to False if the user did not receive a free product or service. No
    OrderNumber Order ID of the contributor's purchase. No
    username Contributor's user name. No
  2. If a key-value pair includes a reserved character, you must URL-encode the character.

    For example, the string Jacob'sLadder must be encoded to Jacob%27sLadder.

Step 4: Encode the UAS

Hash and encode the UAS along with your Bazaarvoice shared encoding key to create a UAS token:

  1. To find your shared encoding key, click Technical Setup » Site Profile in the configuration hub. Under Basic Information, copy the value from the Shared Encoding Key field.
  2. Create a URL-encoded query string that includes required and optional parameters, as in this example:

    date=20161225&userid=shopper123&maxage=30&verifiedpurchaser=True
  3. Create a signature by hashing the URL-encoded parameter string with the encoding key.
  4. Hex-encode the URL-encoded parameter string.
  5. Combine the signature and parameter strings.

The following is a server-side, pseudo-code example:

function makeUserToken(encodingKey, parameters) {
  // encode the signature using HMAC SHA-256
  signature = hash_hmac('sha256' , parameters, encodingKey)

  // concatenate the signature and hex-encoded string of parameters
  uas = signature + hex(parameters)

  // return the user authentication string 
  return uas
}

ENCODING_KEY = 'abcd1234'   // BV shared key from config hub
requiredParameters = 'date=20161225&userid=valuedCustomer'
extraParameters = 'maxage=90&verifiedpurchaser=True'
allParameters = requiredParameters + '&' + extraParameters

userAuthString = makeUserTokenHmac(ENCODING_KEY, allParameters)

Step 5: Provide a UAS token

If you are using BV loader (bv.js), set up integration code to include the generated UAS token in a meta element in the page head element. Include this token on any pages you have Conversations integration code, such as on your product pages. This property should be provided when users are logged into your site’s authentication system, signaling to Bazaarvoice that the user is logged in.

For example:

<head>
...
<meta name="bv:userToken" content="17743067190f0343f24f7" >
...
</head>

For users who are not logged in to your authentication system, leave the userToken property blank (or leave it out of the integration code).

Note: If your existing implementation uses the scout file (bvapi.js), set up integration code to include the generated UAS token in the $BV.configure() function call instead.

For example:

$BV.configure('global', {
  productId: 'test1',
  userToken: '17743067190f0343f24f75df730dfe58646174653d323031332d30352d3031267573657269643d7465737475736572313233'
});

Step 6: Redirect the user to your container page

If you plan to send links to users and ensure they remain logged in, you can include the bveventid query parameter to ensure that the login pages (set in the configuration hub) redirect users to your hosted Conversations container page. The bveventid parameter signals that the user was trying to write a review before he was redirected to log in. The redirect must include:

  • The bveventid parameter, with its complete, unmodified value. For example:
    bveventid=1234asfr
  • The UAS token; for example:
    bvuserToken=17743067190f0343f24f75df730dfe58646174653d323031332d30352d3031267573657269643d7465737475736572313233

The URL should look similar to this:

https://www.example.com/container.htm?bveventid=123asfr&bvuserToken=17743067190f0343f24f75df730dfe58646174653d323031332d30352d3031267573657269643d7465737475736572313233

Test your site authorization integration

Follow these steps to test and, if needed, troubleshoot your integration:

  1. Browse to your Ratings and Reviews page, and then click the "write a review" link. You should be redirected to your login page and see the bveventid in the page URL. If you are not redirected, then site authentication is not enabled. Contact Bazaarvoice for assistance.
  2. After successful login, verify that you are redirected to the container page, and that the bveventid and UAS token are present in the container page URL. If they are not present, then you may not be correctly checking for the bveventid, and should check to ensure you have precisely followed the integration steps.
  3. Verify that you are then redirected to the product page (where you clicked "Write a review"), and that the submission form is present. (Verify that the bveventid is present, and that it matches the one you verified in Step 1). Further, verify that the UAS token is present and valid.

Site authentication requires users to log in to your site’s authentication system. Before users can submit product reviews, questions, or answers, they must log in with the same credentials they used to access your site. Use this method only if you have a legal or business requirement that requires your customers log in to Conversations.

For an overview of site and hosted authentication, including a workflow of each, refer to User authentication.

  1. Using the configuration hub, click User authentication under Settings and then perform these tasks:
    1. Click the Site Authentication Integration tab.
    2. Enable the Require site authentication option.
    3. Enable the Inject Nickname Data option (optional).
    4. Set Provide email address on submission to Required (optional).
    5. Enter a web address (URL) for Staging site login URL. Test users on your staging site will be redirected to log in here before writing reviews.
    6. Enter a web address (URL) for Production site login URL. Users on your production site will be redirected to log in here before writing reviews.
  2. Click Technical Setup and then copy the Shared Encoding Key.
  3. Generate a user authentication string (UAS).
  4. Include the UAS token in the integration code on your product display pages.
  5. Ensure the login page redirects to the container page when the bveventid query parameter is present.

Refer to these code examples as needed.