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 Ratings & Reviews to your site’s sign-in process. Use site authentication only if you have a legal or business requirement that necessitates that your customers sign in to Ratings & Reviews.
In-depthQuick Start

Site authentication requires users to sign in to your site’s authentication system. Before users can submit product reviews, questions, or answers, they must sign 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 sign in to Ratings & Reviews.

Here is the workflow of hosted and site authentication:

Hosted Authentication Site Authentication

Integrate with Ratings & Reviews

To successfully integrate with Ratings & Reviews 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 Ratings & Reviews:

  1. Sign in to the Bazaarvoice Portal .
  2. From the Portal menu, select Configuration.
  3. Select the instance and Go to Configuration. The Site Manager appears, listing the available deployment zones and implementations.
  4. From the Implementations section, select Edit next to the implementation you want to configure.
  5. In the Settings section of the configuration hub, select User authentication.
  6. At the top of the User Authentication page, select the Site Authentication Integration tab to display the Authentication Integration page.
  7. Enable the Require site authentication option.
  8. Determine whether you want to enable the Inject Nickname Data option. Refer to Inject data using site authentication for information about injecting nickname data.
  9. 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.
  10. Enter a web address (URL) for Staging site login URL. Test users on your staging site will be redirected to sign in here before writing content.
  11. Enter a web address (URL) for Production site login URL. Users on your production site will be redirected to sign in here before writing content.

Step 2: Host a container page and reference its URL from Ratings & Reviews

The container page facilitates site authentication redirects.

Create the container page on the same domain where Ratings & Reviews 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 Ratings & Reviews 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. Select the Site Authentication Integration tab.
  5. Enter the staging site sign-in URL in Staging site login URL.
  6. Enter the production site sign-in 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. Yes
    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
    affiliation Automatically adds the default Staff affiliation badge () to submissions that use this URL. This badge indicates that the person writing the review is employed by your company. (Learn more about badges here.) Set this parameter to staff. 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=20230915&userid=shopper123&maxage=30&verifiedpurchaser=True&subjectids=product1/product2/product3
  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)
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;
import java.nio.charset.StandardCharsets;

public String makeUserTokenHmac(String encodingKey, String parameters)
{
  Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
  SecretKeySpec secret_key = new SecretKeySpec(encodingKey.getBytes(), "HmacSHA256");
  sha256_HMAC.init(secret_key);

  String hash = Hex.encodeHexString(sha256_HMAC.doFinal(parameters.getBytes()));
  String hexParameters = Hex.encodeHexString(parameters.getBytes(StandardCharsets.UTF_8));

  return hash + hexParameters;
}
var crypto = require('crypto');

function makeUserTokenHmac(encodingKey, parameters) {
  let hmac  = crypto.createHmac('sha256', encodingKey).update(parameters);
  let signature = hmac.digest('hex');

  let hexParameters = parameters.split('')
                                .map(c => c.charCodeAt(0).toString(16))
                                .join('');

  return signature + hexParameters;
}
require 'openssl'

def makeUserTokenHmac(encodingKey, parameters)
  hash = OpenSSL::HMAC.digest('sha256', encodingKey, parameters)
  signature = hash.unpack('H*').first

  hexParameters = parameters.unpack('H*').first

  return "#{signature}#{hexParameters}"
end
<?php
function makeUserTokenHmac($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 . bin2hex($parameters);

  // return the user authentication string
  return $uas;
}
?>
using System;
using System.IO;
using System.Text;
using System.Security.Cryptography;

namespace uasC {
    class Program {
        static void Main(string[] args) {
            const string SharedKey = "SHAREDKEYGOESHERE";
            string userId = "date=20190708&userid=9100040964&maxage=30";
            using(HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(SharedKey))) {
                string userIdSignature = BytesToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(userId)));
                string hexUserId = BytesToHexString(Encoding.UTF8.GetBytes(userId));
                Console.WriteLine(userIdSignature + hexUserId);
            }
            string BytesToHexString(byte[] input) {
                StringBuilder sb = new StringBuilder(64);
                for (int i = 0; i < input.Length; i++) {
                    sb.Append($ "{input[i] :X2}");
                }
                return sb.ToString();
            }
        }
    }
}

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 Ratings & Reviews integration code, such as on your product pages. This property should be provided when users are signed into your site’s authentication system, signaling to Bazaarvoice that the user is signed in.

For example:

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

Always place meta tags (such as userToken) before the BV loader (bv.js) script tag. When the BV loader loads, it only sees what is visible in the DOM at that time. If a meta tag is placed after the BV loader, it won't be visible to the BV loader at load time. If it is placed before the BV loader, it will be visible.

For users who are not signed 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 signed in, you can include the bveventid query parameter to ensure that the sign-in pages (set in the configuration hub) redirect users to your hosted Ratings & Reviews container page. The bveventid parameter signals that the user was trying to write a review before he was redirected to sign 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 & Reviews page, and then select the "write a review" link. You should be redirected to your sign-in 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 sign-in, 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 selected "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 sign in to your site’s authentication system. Before users can submit product reviews, questions, or answers, they must sign 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 sign in to Ratings & Reviews.

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

  1. Using the configuration hub, select User authentication under Settings and then perform these tasks:
    1. Select 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 sign 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 sign in here before writing reviews.
  2. Select 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 sign-in page redirects to the container page when the bveventid query parameter is present.

Refer to these code examples as needed.