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 user-generated content (UGC) (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 UGC 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:

1. Build the form

• Make a GET or POST request including action= or omit the action parameter. The response to this request includes the information necessary to build a dynamic web form.

2. Preview the author's input

• Make a GET or POST request including action=preview and 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.

3. Submit author input to be saved by Bazaarvoice
   • Make a POST request including action=submit and 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.

The content below details the submission parameters and request methods involved in the three submission processes mentioned above.

📘

More information about the submission process can be found at Submission Fundamentals.

1. Content Type

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

2. Subject Type parameter

The subject of the authored UGC 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

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]

3. Author identification parameter

Depending on the configuration, submission accepts plain text &UserId or Encoded Auth String &User parameters. A client's configuration details the expected submission parameters.

📘

The UserID is an unique id that should only contain

1. Alphanumeric characters, hyphens (-), and underscores (_). No other special characters should be used.
2. Do not use email addresses or any other personally identifiable information for this value.

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

4. Authenticity - Device Fingerprinting & IP

Bazaarvoice stands by its policy of preserving an authentic voice for all UGC. 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 &Action parameter.
• 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 https://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.

JSON Response

{
"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.

📘

The UserID is an unique id that should only contain

1. Alphanumeric characters, hyphens (-), and underscores (_). No other special characters should be used.
2. Do not use email addresses or any other personally identifiable information for this value.

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:

https://[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  
        },  
        ......

📘

The userId must already be submitted to the Bazaarvoice system before the pre-populate values are available. But when UAS is already present, the 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 HTTPS GET or HTTPS 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.

https://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 in the form then user is able to submit the form and all the user input values.

Submitting the form

At the point where errors are no longer found when validating the form, the next step is to use the HTTPS 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 &Action parameter must equal Submit e.g. &Action=Submit.
• The request must use the HTTPS POST request method. Previous requests to build the form and validate fields could be accomplished using HTTPS GET or HTTPS 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 HTTPS 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.