Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Submission Walkthrough
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
Full submission to the Conversations API is a multi-step process that entails building the form, validating the author's input and ultimately POST-ing the provided values.
Introduction
This tutorial is intended to provide developers a complete picture of the submission process. Bazaarvoice accepts various types of consumer-generated content (CGC) (Reviews, Review Comments, Questions, Answers, etc.), and while submission content differs for each of content types, the submission process remains the same. For this tutorial, the discussion will elude to a generic submission but is relevant for the submission process of all content types.
Background
Submission Fundamentals introduces submission using the Bazaarvoice Conversations API. The various authored CGC types, as well as the necessary parameters are detailed in the documentation. It is assumed developers have already completed that documentation.
Submission to the Bazaarvoice platform is designed to be a three step process:
- Build the form
- Make a GET or POST request including
action=or omit theactionparameter. The response to this request includes the information necessary to build a dynamic web form.
- Make a GET or POST request including
- Preview the author's input
- Make a GET or POST request including
action=previewand the author's input. Bazaarvoice will return user input errors (Ex: missing required fields) as appropriate or if there are no errors the response will represent the competed form.
- Make a GET or POST request including
- Submit author input to be saved by Bazaarvoice
- Make a POST request including
action=submitand the author's input. If there are user input errors the response will be identical to a preview request with errors. If there are no errors Bazaarvoice will save the data and return a submission ID.
- Make a POST request including
The content below details the submission parameters and request methods involved in the three submission processes mentioned above.
-
Submission must be associated with one a single type of content. This is accomplished by specifying the API endpoint.
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[latestApiVersion]&PassKey=[yourApiKey]&ProductId=[productId]&Action=[submissionAction]&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]The table below details the complete list
Content type Submission Endpoint Review Review Comment Question Answer Story submitstory.json
Story Comment submitstorycomment.json
-
The subject of the authored CGC must be identified. This is done using a parameter to identify the subject. For instance, reviews are submitted about products, questions are submitted about reviews, comments are submitted about reviews, and answers are submitted about questions.
The table below details the complete list
Content type Submission Endpoint Subject Type Parameter Review ProductId Review Comment ReviewId Question ProductID | CategoryId Answer QuestionID Story submitstory.json
CategoryId | ProductId Story Comment submitstorycomment.json
StoryId GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[latestApiVersion]&PassKey=[yourApiKey]&ProductId=[productId]&Action=[submissionAction]&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname] -
Depending on the configuration, submission accepts plain text
&UserIdor Encoded Auth String&Userparameters. A client's configuration details the expected submission parameters.GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[latestApiVersion]&PassKey=[yourApiKey]&ProductId=[productId]&Action=[submissionAction]&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&UserId=1234567 -
Bazaarvoice stands by its policy of preserving an authentic voice for all CGC. When submitting content, we require you also submit the IP address and the device fingerprint. The following tutorials describe how to submit IP address and device fingerprint:
- The IP address from where the content submitted
- The Device Fingerprint
Additionally, data submitted by the end user may not be modified in any way or form before being submitted to the Bazaarvoice API. The submission must be completely the voice of the end user.
Cross-domain submission
Form submission (action=submit) is supported from the browser using CORS. Refer to the CORS tutorial for more details.
Building the form
Rather than rely on a hard-coded submission form solution many clients need a dynamic or flexible submission form creation process. Within Bazaarvoice, this is supported by allowing different product category configurations. Said another way, products can belong to a product category, and those product categories may have unique submission fields.
For example, imagine an online store that sells electronics. While submitting a review on video equipment you might want the consumer to answer questions about streaming video services. But including a streaming video question for reviews on home appliances does not seem contextually appropriate. Building numerous review submission forms for all the product variances would be costly and difficult to maintain. A better solution is to build the submission form dynamically. The How to Build a Submission Form tutorial was created to help developer`s understand this process.
Not all clients have the need to dynamically create the submission forms. However those clients that do, can obtain metadata about submission to help them build the form through sending an API request. Metadata such as the fields elements, minimum and maximum values, and other information about how the data should be structured on the form are discussed in the tutorial.
The requests may be made to obtain the metadata about the submission form can be accomplished in a couple ways:
- send a request to the proper endpoint without any
&Actionparameter. - send a request to the proper endpoint including an empty
&Action=parameter in the request.
The following cURL is an example of a request used to obtain data in a response which can be used in building a submission form:
curl http://stg.api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&ProductId=1000001&UserId=craiggsdsdil&UserNickname=cswwswsgil&passkey=2cpdrhohmgmwfz8vqyo48f52g&action=
The sample response exposes the fields node which a developer can iterate over to build a submission form.
{
"HasErrors": true,
"Data": {
"GroupsOrder": [....],
"Groups": {....},
"Fields": {
"isratingsonly": {
"Default": null,
"MaxLength": null,
"Value": "false",
"Required": true,
"Type": "BooleanInput",
"Label": null,
"Id": "isratingsonly",
"MinLength": null,
"Options": []
},
"isrecommended": {
"Default": null,
"Value": null,
"MaxLength": null,
"Required": false,
"Type": "BooleanInput",
"Label": null,
"Id": "isrecommended",
"MinLength": null,
"Options": []
},
"reviewtext": {
"Default": null,
"Value": null,
"MaxLength": 10000,
"Required": true,
"Type": "TextAreaInput",
"Label": null,
"Id": "reviewtext",
"Options": [],
"MinLength": 50
},
"title": {
"Default": null,
"Value": null,
"MaxLength": 150,
"Required": true,
"Type": "TextInput",
"Label": null,
"Id": "title",
"Options": [],
"MinLength": 0
},
"usernickname": {
"Default": null,
"Value": "cswwswsgil",
"MaxLength": 25,
"Required": true,
"Type": "TextInput",
"Label": null,
"Id": "usernickname",
"Options": [],
"MinLength": 4
},
"useremail": {
"Default": null,
"Value": null,
"MaxLength": 255,
"Required": true,
"Type": "TextInput",
"Label": null,
"Id": "useremail",
"Options": [],
"MinLength": 0
},
"rating": {
"Default": null,
"Value": null,
"MaxLength": null,
"Required": true,
"Type": "IntegerInput",
"Label": null,
"Id": "rating",
"MinLength": null,
"Options": []
},
....
},
"FieldsOrder": [....]
},
"Form": [....],
"AuthorSubmissionToken": null,
"FormErrors": {....
}
A more detail description of building the form can be found at the How to Build a Submission Form tutorial.
Pre-populate the form with a user's ID
Minimizing the number of form fields an author is required to complete encourages both form completion and consistent data. It's beneficial to pre-populate form fields with user-data input values when possible. Think about visiting sites that maintain account information. It is a poor user experience to continue to request account information if the site has already captured it before.
Such a process is possible when using either of the Bazaarvoice authentication types, Client Mastered authentication or Bazaarvoice Mastered authentication. By including the correct UserId | User parameter in the request while building the submission form, the Response will return all known user string values. The following is a sample Request and Response:
http://[stg.]api.bazaarvoice.com/data/submitreview.[FORMAT]?ApiVersion=[latestApiVersion]&ProductId=[productId]&PassKey=[yourKey]&User|UserId=[valueOfUserOrUserId]
....
},
"Fields": {
"usernickname": {
"Default": null,
"Value": "SmartShopper",
"MaxLength": 25,
"Required": true,
"Type": "TextInput",
"Label": null,
"Id": "usernickname",
"Options": [],
"MinLength": 4
},
......
fields elements are returned data associated with the "Value" key.
In cases where the client is using Bazaarvoice-mastered authentication and the authentication string exist, content submission requests may omit the HostedAuthentication_AuthenticationEmail and HostedAuthentication_CallbackURL parameters.
A complete discussion of authentication types is also available.
Collecting user's input
With the form built, it's now time for the author to complete the form.
Using data from the previous API response, helper text can be positioned to aide the author in completing the form. For instance labeling an input with the maximum character limits. This is also an ideal time to catch as many author input errors as possible. This can be accomplished using client side validation (e.g. JavaScript). Using the metadata provided in the Fields element mentioned above, developers should create client side validation rules. This will minimize the possibility of getting any errors upon form submission. An example of client side validation is combining the MinLength, MaxLength, and Required Fields object with JavaScript to ensure a customers' input is what the API expects.
Authors should not submit encoded characters, including HTML. As a reminder, author input is communicated to Bazaarvoice using percent encoded key=value pairs. Marked up content will break moderation, is a security risk, and the submission will be rejected. Submission forms should not include WYSIWYG editors, only standard text inputs. The Open Web Application Security Project (OWASP) maintains a list of security policies which developers should adhere to.
Validating the form
After an author has satisfactorily provided form values, the form can be submitted to the API containing the Action parameter equal to "Preview" (&Action=Preview). This provides additional validation against the API, which client side validation often cannot catch. Submitting the form for validation to the API may be done using either the HTTP GET or HTTP POST request methods. Submission using the &Action=Preview also be complete using JSONP.
The following request/response represents an interaction that found an error when submitting to the API. In this example, a review has already been submitted for the specified product (&ProductId=1000001) for that userId (&UserId=craiggil). The client instance is not allowed to accept duplicate review, so an error is produced. This is an example which the client side validation could not catch.
http://stg.api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&ProductId=1000001&UserId=craiggil&UserNickname=cgil&passkey=2cpdrhohmgmwfz8vqyo48f52g&action=preview
{
Data: { },
HasErrors: true,
Form: [ ],
AuthorSubmissionToken: null,
FormErrors: { },
TypicalHoursToPost: null,
SubmissionId: null,
Locale: null,
Errors: [
{
Message: "",
Code: "ERROR_DUPLICATE_SUBMISSION"
}
]
}
One form validation strategy is to first display an empty form intended to capture the end user's input. Client side validation is happening as the author completes the form. When the end user submits the form data, it is sent to the API using the &Action=Preview parameter. Then, the end user is taken to a page to 'review' their submission. This provides the opportunity to present, and correct, any errors that may have results from submitting to the API using &Action=Preview. If no errors are present, the form the user is able to submit the form and all the user input values.
Submitting the form
At the point where errors no longer are found when validating the the form, the next step is to use the HTTP POST request to submit the data to Bazaarvoice. Similar to validating the form data, the data is again submitted to the Bazaarvoice endpoint. The differences when actually submitting the data are the following:
- The
&Actionparameter must equal Submit e.g.&Action=Submit. - The request must use the HTTP POST request method. Previous requests to build the form and validate fields could be accomplished using HTTP GET or HTTP POST.
POST /data/submitreview.json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress] ... ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]
Ellipses (...) in above example indicate that your app may generate other headers.
A successful POST to Bazaarvoice will result in the response containing a SubmissionId value.
{
"Data":{},
"HasErrors":false,
"Form":[],
"FormErrors":{},
"TypicalHoursToPost":72,
"SubmissionId":"3bjfuudsrjt516vitpvwnqrli",
"Review":{
"SendEmailAlertWhenPublished":false,
"SendEmailAlertWhenCommented":false,
"SubmissionTime":"2011-11-16T13:51:01.196-00:00",
"Rating":5,
"IsRecommended":false,
"ReviewText":"test test test test test test test test",
"TypicalHoursToPost":null,
"Id":null,
"SubmissionId":null,
"Title":"This product is really nifty"
},
"Locale":"en_US",
"Errors":[]
}
Post submission success
Submission confirmation
The form has been submitted, accepted, and the response contains a SubmissionId value. Congrats. Now what?
The following is an example of a successful Review Submission response after submitting the form by HTTP POST:
{
"Data":{},
"HasErrors":false,
"Form":[],
"FormErrors":{},
"TypicalHoursToPost":72,
"SubmissionId":"3bjfuudsrjt516vitpvwnqrli",
"Review":{
"SendEmailAlertWhenPublished":false,
"SendEmailAlertWhenCommented":false,
"SubmissionTime":"2011-11-16T13:51:01.196-00:00",
"Rating":5,
"IsRecommended":false,
"ReviewText":"test test test test test test test test",
"TypicalHoursToPost":null,
"Id":null,
"SubmissionId":null,
"Title":"This product is really nifty"
},
"Locale":"en_US",
"Errors":[]
}
Presenting the submission inputs back to the user assures the author that their submission was accepted. The successful response contains information which is useful to surface to the end user who just completed the form. This includes a summary of the submission (Rating, Title, ReviewText, and TypicalHoursToPost). Also, you should communicate to the author that their submission will not be immediately available due to moderation. The TypicalHoursToPost time provides an indication of when the submission will be available.