Search form

Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.

BV-Mastered

The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

This tutorial will show you the components you will need to implement Bazaarvoice-mastered authentication via the Bazaarvoice Conversations API and how the process works.

Overview

Bazaarvoice-mastered authentication allows users to submit content without prior authentication. This is useful for sites whose logins are difficult to customize or for sites that don't have account creation capabilities. Further our experience has shown that up to 40% of potential content authors will not complete the submission process if they are required to login first. Bazaarvoice-mastered authentication can raise your submission rate.

Components

The following table summarizes the components you will need to understand in order to implement Bazaarvoice-mastered authentication. These components will be referenced throughout the rest of this documentation. Familiarizing yourself with them will make understanding Bazaarvoice-mastered authentication easier.

Component Description Responsiblity
Submission form This a web form you build and host. Authors will use it to submit content (reviews, questions, etc). client
Authentication email This email, which is typically sent by Bazaarvoice, asks the user to confirm they submitted the content by clicking on a link including a unique auth token. Clicking on the link opens a URL to your verification service. Bazaarvoice or client (see below)
Auth token This is a unique string created by Bazaarvoice for the purpose of confirming an author has access to the email address they submitted along with their content. It is used by your authentication service and should not be confused with the encoded UAS. Bazaarvoice
User authentication service You will make a service that will perform an API request to submit the authentication token from the email to the Bazaarvoice Conversations platform. A successful authentication with return an encoded user authentication string (UAS). client
Encoded user authentication string (UAS) An encoded UAS communicates user ID as well as other user attributes to Bazaarvoice and can be used to identify the author during submission in place of an email address. The encoded UAS is not the same as the auth token. Bazaarvoice
An encoded UAS persistence mechanism A mechanism to persist the encoded UAS for use in future submissions. This is commonly achieved by storing a cookie in the user's browser. client

Walk-through

How it works

  1. Submit content

    The process starts with a content submission to the Bazaarvoice Conversations platform.

  2. Authentication email sent to content author

    Next, the Bazaarvoice platform triggers an email to the user that submitted the content.

  3. Author clicks authentication link in email

    The verification email contains a link with a token that you will use in your user authentication service.

  4. User authentication

    Your authentication service will make an API request to submit the authentication token from the email to the Bazaarvoice Conversations platform.

  5. Persist User ID

    Finally, if the user is verified, the API will return the user ID that you must use in subsequent submission for that user.

Step 1: Submit content

For content submission with Bazaarvoice-mastered authentication you will need to submit two parameters, HostedAuthentication_AuthenticationEmail and HostedAuthentication_CallbackURL.

Bazaarvoice-mastered authentication parameters

Name Value Description
HostedAuthentication_AuthenticationEmail Email address This parameter tells the Bazaarvoice platform where to send the email that will contain the authentication link. It overrides anything submitted in the useremail field.
HostedAuthentication_CallbackURL URL This URL will be used in Step 4 as the front-end to your authentication service. This parameter does not appear in the API response because it does not represent a user facing question. You should submit this value with no input from content authors. This URL must be white-listed. See the appendix to learn more about white-listing.

Here is an example of a submitreview.json POST request that has these two parameters:

POST request

The following code applies to full submission only. It does not apply to progressive submission.
POST /data/submitreview.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...

PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.4&ProductId=test1&Rating=5&ReviewText=api+hosted+auth+submission+test+api+hosted+auth+submission+test+api+hosted+auth+submission+test+&Title=api+hosted+auth+submission+test+2&UserNickname=apihostauthsubtester&HostedAuthentication_AuthenticationEmail=test.user%40bazaarvoice.com&HostedAuthentication_CallbackURL=http%3A%2F%2Fwww.example.com%2Fyour%2Fauthentication-service

Ellipses (...) in above example indicate that your app may generate other headers.

Step 2: Authentication email sent to content author

The Bazaarvoice platform triggers an email to the user with a authentication link that is made up of the URL you submitted in the HostedAuthentication_CallbackURL parameter. Here's an example:

http://www.example.com/your/authentication-service?bv_authtoken=a7a4278ff33887d352fcdef30edd143f487dc881
The bv_authtoken found at the end of the authentication URL is not the same as the AuthorSubmissionToken that is found in the response of a successful submitreview.json request.

The last part of that URL is the token you use in the authenticateuser.json request to verify the user.

Who sends the authentication email?
Our Conversations platform is designed to use the Bazaarvoice white label email service provider (ESP) to send the emails. Clients on our Conversations PRR platform can be configured to use either their ESP or our white label ESP. If you have any questions about which one your instance uses, contact Bazaarvoice Support.

Step 3: Author clicks authentication link in email

Once the user gets that email they should click on that authentication link to your site's authentication page. Here is an example of the message the platform would send:

The link that the red arrow is pointing at will direct the user to the web page on your site that exposes your user authentication service.

Step 4: User authentication

When using the Conversations API you will construct and host an authentication service consisting of a server side component that executes the authenticateuser.json request and a client side component that displays the results as well as persists the users identity for future submissions (see step 5)..

Your authentication service page must be white-listed. See the appendix to learn more.

Upon clicking the authentication link from Step 3 the user will be sent to your user authentication service along with a token added by the Bazaarvoice platform. Your service will then submit that token to Bazaarvoice to verify the user. Here's an example of that request

POST request

POST /data/authenticateuser.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...

PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.4&authtoken=a7a4278ff33887d352fcdef30edd143f487dc881

Ellipses (...) in above example indicate that your app may generate other headers.

Response

Highlighted in the response is the User Authentication String that the Bazaarvoice platform returns.

{
    "Data": {},
    "HasErrors": false,
    "Form": [],
    "AuthorSubmissionToken": null,
    "FormErrors": {},
    "TypicalHoursToPost": null,
    "SubmissionId": null,
    "Locale": "en_US",
    "Errors": [],
    "Authentication": {
        "User": "6ed12da604cc75b8613f7e209d07987b696e7465726e616c5f7375626d7373696f6e3d74727565267573657269643d616a6d66716176737836786f7068626e7571656474726a347a26757365726e616d653d617069686f73746175746873756274657374657226686f737465643d564552494649454426646174653d3230313430353036266d61786167653d333635"
    }
}

That is the UAS that the Bazaarvoice platform assigns to this verified user.

Step 5: Persist user ID

You can make submission for your users convenient by cookieing that user's browser with the User Authentication String from the response example in step 4. Then you can use that value in subsequent content submission requests and omit the HostedAuthentication_AuthenticationEmail and HostedAuthentication_CallbackURL parameters.

This example uses the token returned from the authenticateuser.json request as a submitreview.json request:

POST /data/submitreview.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded

PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.3&ProductId=test1&Rating=5&ReviewText=api+hosted+auth+submission+test+api+hosted+auth+submission+test+api+hosted+auth+submission+test+&Title=api+hosted+auth+submission+test+&UserNickname=apihostauthsubtester&action=submit&User=6ed12da604cc75b8613f7e209d07987b696e7465726e616c5f7375626d7373696f6e3d74727565267573657269643d616a6d66716176737836786f7068626e7571656474726a347a26757365726e616d653d617069686f73746175746873756274657374657226686f737465643d564552494649454426646174653d3230313430353036266d61786167653d333635

By persisting that value with that user (via the browser) all the content submitted on that device can be tied to that user ID. This way you get all the benefits of your users having a profile without the cost of maintaining those user profiles.

Appendix

Authentication service white-listing

During the authentication process Bazaarvoice will send an email to your users soliciting them to click a link to your authentication service...or is it?

The link to your authentication service is communicated to Bazaarvoice during the content submission process using the HostedAuthentication_CallbackURL. This means it is possible to perform a submission using somebody else's email address and a URL to a malicious page. That somebody else would then receive an email with the malicious URL represented as a authentication link. This is referred to as an unvalidated redirect.

To protect against unvalidated redirects Bazaarvoice requires that the domain hosting your authentication service be validated by being white-listed in our system. Content submissions including a HostedAuthentication_CallbackURL with an unvalidated domain will be rejected with an error:

{
    "Data":{},
    "HasErrors":true,
    "Form":[],
    "AuthorSubmissionToken":null,
    "FormErrors":{},
    "TypicalHoursToPost":null,
    "SubmissionId":null,
    "Locale":null,
    "Errors":[
        {
            "Message":"Invalid domain name: example.com",
            "Code":"ERROR_PARAM_INVALID_PARAMETERS"
        }
    ]
}

Contact Bazaarvoice Support to white-list your authentication service domains.