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
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
-
Submit content
The process starts with a content submission to the Bazaarvoice Conversations platform.
-
Authentication email sent to content author
Next, the Bazaarvoice platform triggers an email to the user that submitted the content.
-
Author clicks authentication link in email
The verification email contains a link with a token that you will use in your user authentication service.
-
User authentication
Your authentication service will make an API request to submit the authentication token from the email to the Bazaarvoice Conversations platform.
-
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
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 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)..
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.