Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Progressive Submission
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
Introduction
This tutorial explains how to use the progressive submission endpoints. These endpoints are available as part of the Conversations API.
Overview
Progressive submission improves review content collection in two ways:
- By allowing collection of reviews on multiple products; and
- By allowing incremental submission of review attributes
The combination of these two functionalities makes it especially valuable for clients that sell multiple items to a consumer at once. This will improve review coverage across products as well as the content submission rate.
Additionally, the incremental submission functionality may be used to enhance existing single product review submissions. This will improve content submission using this simplified approach.
The flow-chart below is a summary of a multi-product submission process using the progressive submission endpoints:
As previously described, progressive submission also supports the ability to collect review partials (i.e. ratings, review text, title, context data values) over multiple sessions. Reviews can be submitted for moderation once the required fields are completed. This is determined by the isFormComplete field. Partial reviews can be iterated over using the submissionSessionToken.
Components
The following table summarizes the components you will need to understand in order to implement progressive submission. These components will be referenced throughout the rest of this documentation.
| Component | Description | Responsibility |
|---|---|---|
| Submission form | This a web form you build and host. Authors will use it to submit reviews. | client |
| UserToken | The UserToken is an encoded set of fields sent in the body that are authenticated via an HMAC generated with the client's encodingKey. Must contain userId. Read more about userToken.The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
| UserId | Unique id for user. Can either be sent seprately at this level, or be encoded in UserToken. The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
| submissionSessionToken | Unique token ID required for progressive submission of the review. | Bazaarvoice/client |
| preview parameter | Query string parameter indicating if content should be submitted for moderation. Used with the progressiveSubmit.json endpoint. Read more about the preview parameter. |
Bazaarvoice/client |
| isFormComplete parameter | A boolean value returned as a query string parameter indicating if content should be submitted for moderation. Used with the progressiveSubmit.json endpoint. | Bazaarvoice/client |
Walk-through
How it works
-
Request reviews
Solicit reviews from consumers.
-
Initiate progressive submission
Request form data on product(s) using the initiateSubmit.json endpoint. For additional metadata about the product, you will also need to request data from the products endpoint.
-
Build product(s) submission form
Build the submission form(s) for the given productId(s). Render the HTML controls and values for the product submission form.
-
Submit product(s) review
Handle the productId(s) submissions. Use the
previewparameter in the request to stage the review submission and theisFormCompletein the response to observe if all the required fields are provided.
Step 1: Request reviews
Consumers are asked to provide reviews. This often comes through a post interactive email (PIE) containing a link to 'write reviews on your purchase'.
The user clicks the link in the email and is shown review submission forms for any number of products.
Other methods to solicit a shopper's feedback are also possible, such as hosting a recently purchased page where shoppers can leave reviews.
Step 2: Initiate Progressive Submission
Products may have different review attributes. For instance while a review form for an article of clothing may ask 'how was the fit', that question does not make sense for an electronics good.
The purpose of the initiateSubmit.json call is to provide API users with data to create the review submission form for a given productId. The endpoint accepts an array of productIds in the body parameter.
initiateSubmit.json - Client Mastered Authentication
Below are the details to be used when using initiateSubmit using client mastered authentication
| Name | Description | Required |
|---|---|---|
format |
Data format. Set this value to "json". |
Yes |
Query string |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
The API version, e.g. 5.4. |
Yes |
extended |
This parameter is sent as a single key and does not need a value. When omitted, the When included, |
No |
Header |
||
Content-Type |
Set this value to "application/json". |
Yes |
Body |
||
productIds |
Array of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended. |
Yes |
UserToken |
The UserToken is an encoded set of fields sent in the body that are authenticated via an HMAC generated with the client's encodingKey. Must contain userId. Read more about userToken.The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
UserId |
Unique id for user. Can either be sent seprately at this level, or be encoded in UserToken. The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
locale |
Yes |
|
deviceFingerprint |
Unique identifier for author's device. Read more about deviceFingerprint |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
POST request
POST /data/initiateSubmit.json?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion} HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/json
X-Forwarded-For: [AuthorIPAddress]
...
{
"locale": "en_US",
"userToken": "{USER_TOKEN}",
"productIds": [
"Product1",
"ProductZ"
]
}
Ellipses (…) in above example indicate that your app may generate other content.
initiateSubmit.json response
The following response is a sample from a HTTP POST to the initiateSubmit.json endpoint:
{
"hasErrors": false,
"response": {
"userNickname": "USER_NICKNAME",
"productFormData": {
"wbk003xl": {
"review": {
"submissionID": "qbk13gsqk9ffyqbwhs2y51m2z",
"productExternalID": "wbk003xl",
"submissionTime": "2019-08-06@20:43:47"
},
"fieldsOrder": [
"rating",
"title",
"reviewtext",
....
],
"fields": {
"rating": {
"id": "rating",
"type": "integer",
"class": "rating"
},
"Gender": {
"valuesLabels": {
"Male": "Male",
"Female": "Female"
},
"autoPopulate": true,
"label": "What is your gender?",
"id": "contextdatavalue_Gender",
"type": "choice",
"class": "cdv",
"required": false
},
"title": {
"required": true,
"id": "title",
"maxLength": 50,
"type": "text",
"class": "title"
},
"reviewtext": {
"required": true,
"id": "reviewtext",
"minLength": 50,
"type": "text",
"class": "reviewtext"
},
...
},
"submissionSessionToken": "qbk13gsqk9ffyqbwhs2y51m2z_caa2ab8becea612e79d7c5abe31de4877267d744ac3f157816bb55e1aef2037c_X2E6cHCr5bs="
},
"wsd005c": {
"review": {
"submissionID": "q2wxet06q1xfp6onq906uze57",
"productExternalID": "wsd005c",
"submissionTime": "2019-08-06@20:43:47"
},
"fieldsOrder": [
"rating",
"title",
"reviewtext",
....
],
"fields": {
"rating": {
"id": "rating",
"type": "integer",
"class": "rating"
},
"Gender": {
"valuesLabels": {
"Male": "Male",
"Female": "Female"
},
"title": {
"required": true,
"id": "title",
"maxLength": 50,
"type": "text",
"class": "title"
},
"reviewtext": {
"required": true,
"id": "reviewtext",
"minLength": 50,
"type": "text",
"class": "reviewtext"
},
...
},
"submissionSessionToken": "q2wxet06q1xfp6onq906uze57_4a4e35f8a38ad43859fe5433c8bdeb4c7e1bfff0944252a8b866b44c4114e5ac_JKAYiolGI+g="
}
}
}
}
initiateSubmit.json - Hosted Authentication
Below are the details to be used when using initiateSubmit using hosted authentication
Parameters
| Name | Description | Required |
|---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
extended |
This parameter is sent as a single key and does not need a value. When omitted, the When included, |
No |
hostedauth |
Indicates the action being performed, is using hosted authentication |
Yes |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productIds |
Array of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended. |
Yes |
locale |
Locale for content |
Yes |
deviceFingerprint |
Unique identifier for author's device. Read more about deviceFingerprint |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
POST request
curl -X POST \
'http://stg.api.bazaarvoice.com/data/initiateSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4&action=submit&hostedauth' \
-H 'Content-Type: application/json' \
...
{
"locale": "en_US",
"productIds": [
"Product1"
]
}
Ellipses (…) in above example indicate that your app may generate other content.
initiateSubmit.json response
The following response is a sample from a HTTP POST to the initiateSubmit.json endpoint:
{
"hasErrors": false,
"response": {
"productFormData": {
"product1": {
"review": {
"submissionID": "r116143_16323803KMdC8LfyA8",
"productExternalID": "product1",
"submissionTime": "2021-09-23@06:59:28"
},
"fieldsOrder": [
"rating",
"reviewtext",
"title",
"usernickname",
"authenticationemail",
"photourl_1",
"photocaption_1",
"photourl_2",
"photocaption_2",
"photourl_3",
"photocaption_3",
"photourl_4",
"photocaption_4",
"photourl_5",
"photocaption_5",
"photourl_6",
"photocaption_6",
"videourl_1",
"videocaption_1",
"isrecommended",
"userlocation",
"Age",
"Gender",
"BodyType",
"Quality",
"Value",
"Appearance1",
"Fit_22",
"Con",
"BestUsesFlowersGifts"
],
"fields": {
"photourl_6": {
"id": "photourl_6",
"type": "url",
"class": "photourl"
},
"videourl_1": {
"id": "videourl_1",
"type": "url",
"class": "videourl"
},
"BestUsesFlowersGifts": {
"valuesLabels": {
"AnyOccasion": "Any occasion",
"ChristmasGift": "Christmas Gift",
"BirthdayGift": "Birthday Gift",
"ThankYouAppreciation": "Thank you/Appreciation",
"GiftCorporate": "Gift Corporate",
"GiftSympathy": "Gift Sympathy",
"BasketCongratulations": "Basket Congratulations"
},
"autoPopulate": false,
"label": "Best Uses",
"id": "tagid_BestUsesFlowersGifts",
"type": "multichoice",
"class": "tag",
"required": false
},
"photourl_2": {
"id": "photourl_2",
"type": "url",
"class": "photourl"
},
"photourl_3": {
"id": "photourl_3",
"type": "url",
"class": "photourl"
},
"photourl_4": {
"id": "photourl_4",
"type": "url",
"class": "photourl"
},
"photourl_5": {
"id": "photourl_5",
"type": "url",
"class": "photourl"
},
"rating": {
"id": "rating",
"type": "integer",
"class": "rating"
},
"Gender": {
"valuesLabels": {
"Male": "Male",
"Female": "Female"
},
"autoPopulate": true,
"label": "What is your gender?",
"id": "contextdatavalue_Gender",
"type": "choice",
"class": "cdv",
"required": false
},
"BodyType": {
"valuesLabels": {
"Apple": "Apple",
"Curvy": "Curvy",
"FullFigured": "Full figured",
"Hourglass": "Hourglass",
"LongAndLean": "Long and Lean",
"PearShaped": "Pear shaped",
"Slender": "Slender",
"Petite": "Petite"
},
"autoPopulate": false,
"label": "What is your body type?",
"id": "contextdatavalue_BodyType",
"type": "choice",
"class": "cdv",
"required": false
},
"title": {
"required": false,
"hidden": false,
"id": "title",
"maxLength": 50,
"type": "text",
"class": "title"
},
"reviewtext": {
"required": false,
"hidden": false,
"id": "reviewtext",
"minLength": 50,
"type": "text",
"class": "reviewtext"
},
"isrecommended": {
"id": "isRecommended",
"type": "boolean",
"class": "isrecommended"
},
"photocaption_2": {
"id": "photocaption_2",
"type": "text",
"class": "photocaption"
},
"photocaption_1": {
"id": "photocaption_1",
"type": "text",
"class": "photocaption"
},
"Quality": {
"autoPopulate": false,
"label": "How would you rate the quality of this product?",
"id": "rating_Quality",
"type": "integer",
"class": "rating",
"required": false
},
"photocaption_6": {
"id": "photocaption_6",
"type": "text",
"class": "photocaption"
},
"authenticationemail": {
"required": true,
"hidden": false,
"id": "hostedauthentication_authenticationemail",
"type": "text",
"class": "hostedauthentication_authenticationemail"
},
"photocaption_5": {
"id": "photocaption_5",
"type": "text",
"class": "photocaption"
},
"photocaption_4": {
"id": "photocaption_4",
"type": "text",
"class": "photocaption"
},
"photourl_1": {
"id": "photourl_1",
"type": "url",
"class": "photourl"
},
"photocaption_3": {
"id": "photocaption_3",
"type": "text",
"class": "photocaption"
},
"videocaption_1": {
"id": "videocaption_1",
"type": "text",
"class": "videocaption"
},
"Age": {
"valuesLabels": {
"17orUnder": "17 or under",
"18to24": "18 to 24",
"25to34": "25 to 34",
"35to44": "35 to 44",
"45to54": "45 to 54",
"55to64": "55 to 64",
"65orOver": "65 or over"
},
"autoPopulate": true,
"label": "How old are you?",
"id": "contextdatavalue_Age",
"type": "choice",
"class": "cdv",
"required": false
},
"Con": {
"valuesLabels": {
"Bulky": "Bulky",
"Heavy": "Heavy",
"RetainsOdors": "Retains Odors",
"StainsEasily": "Stains Easily"
},
"autoPopulate": false,
"label": "Cons",
"id": "tagid_Con",
"type": "multichoice",
"class": "tag",
"required": false
},
"Appearance1": {
"autoPopulate": false,
"label": "How would you rate the appearance of the product?",
"id": "rating_Appearance1",
"type": "integer",
"class": "rating",
"required": false
},
"usernickname": {
"required": true,
"hidden": false,
"id": "usernickname",
"minLength": 4,
"type": "text",
"class": "usernickname"
},
"Value": {
"autoPopulate": false,
"label": "How would you rate the value of this product?",
"id": "rating_Value",
"type": "integer",
"class": "rating",
"required": false
},
"_Location": {
"required": false,
"hidden": false,
"id": "userlocation",
"type": "text",
"class": "userlocation"
},
"Fit_22": {
"valuesLabels": {
"valueLabel1": "Too small",
"valueLabel2": "A little small",
"valueLabel3": "True to size",
"valueLabel4": "A little big",
"valueLabel5": "Too big"
},
"autoPopulate": false,
"label": "Fit",
"id": "rating_Fit_22",
"type": "integer",
"sliderSize": 5,
"class": "slider",
"required": false
},
"useremail": {
"required": true,
"hidden": false,
"id": "useremail",
"type": "text",
"class": "useremail"
}
},
"submissionSessionToken": "{some_token}"
}
},
"userId": "{some_id}"
}
}
Read more reference documentation on the initiateSubmit.json endpoint.
Step 3: Build product(s) submission form
Building a progressive submission form is similar to building a submission form using the full submission endpoint. High level steps include:
Obtaining product metadata from the products endpoint. This may include product descriptions, images and any other relevant data to help users write a review. Rather than displaying just the questions to review a product, it is often helpful to provide context. Product images, title, and price are just some attributes that help when writing a review.
Review form without any product context.
Review form displaying product context (images, title).
The products endpoint supports passing in a list of productIds to optimize the number of API requests.
Use both the
fieldsOrderandfieldselements from the initiateSubmit.json response to create the HTML controls needed for the submission form.The fieldsOrder lists the required submission questions first, followed by those submission elements set up on the Site Manager.
The field data contains attributes that provide information on the specific HTML controls that should be displayed on the submission form.
The possible field types are shown below
"title": { "required": true, "id": "title", "maxLength": 50, "type": "text", "class": "title" },As you can see, there is a list of name/value pairs that are returned for each
Fieldsobject. The sole purpose of this data is to provide developers a blue print to construct a submission form.Let's take a look at these name/value pairs:
The boolean value
hidden, indicates if the element should be displayed on the form. Only form elements with a true value are returned in the response. When not found in the response,hiddenis false."OrderNumber": { "hidden": true, "autoPopulate": false, "answerLength": "SHORT_LINE", "label": "Order Number", "id": "additionalfield_OrderNumber", "type": "text", "class": "additionalField", "required": false, "maxLength": 35 },An
autoPopulatevalue makes it possible to pre-populated a control when building the form. An example of this is signing a user up to receive a newsletter.newslettersignup: { autoPopulate: true, maxLength: null, value: "true", required: true, type: "boolean", label: null, id: "newslettersignup", minLength: null },The
valuerepresents the user's answer to a question and is what Bazaarvoice will store. When obtaining pre-populated data such as making a request using the &User and/or &UserID parameter, the value is returned in theValuekey.The
maxLengthis configured on the BV side and submissions will not be allowed unless it is met. The value can be used to create client side validation to ensure that the submission form meets the requirement. In the sample below the Review Text must not exceed 5000 characters.reviewtext: { default: null, value: "", maxLength: 50000, required: false, type: "TextAreaInput", label: null, id: "reviewtext", minLength: 50 },⚠ERROR_FORM_TOO_LONGerror will be returned from the API if a submission exceeds themaxLengthvalue.requiredindicates that some value must be provided with submission of the form. Combination ofrequiredandtypecan be used to create client side validation.commenttext: { default: null, value: null, maxLength: 10000, required: true, type: "TextAreaInput", label: null, id: "commenttext", minLength: 1 },⚠ERROR_FORM_REQUIREDwill be returned from the API if a submission is missing aRequiredfield.The
typename/value gives the developer an indication of the HTML control that should be used to capture the input on the form. These values can also be used to generate client side validation rules. Values returned withintypeinclude:- text
- choice
- boolean
- integer
- url
The Inputs Types tutorialis the authoritative source documenting the different field types.
The
labelname/value will return labels for Additional fields, context data, tag dimensions and rating dimensions. If the label is "null", it is up to developers to provide values.The
idvalue can be used to uniquely identify any controls used to build the form. This is also the value developers would use as the key in the submission (i.e id=value). In the HTML it would be the value of the name attribute.The
valuesLabelsis an array of values that have been configured for the parentfieldelement. An example when to use thevaluesLabelsobject, is in forms that contains a drop-down list control. Programmatically a developer would iterate over the array extracting out the values and label to construct HTML. An example is shown below:"valuesLabels": { "1week": "1 week", "1month": "1 month", "3months": "3 months", "6months": "6 months", "1year": "1 year or longer" }, "autoPopulate": false, "label": "Approximately how long have you owned this product?", "id": "contextdatavalue_LengthOfOwnership", "type": "choice", "class": "cdv", "required": false },So programmatically you could end up with something like:
"choice" is thetypevalue when thevaluesLabelsarray is populated.The
minLengthis configured on the Bavaarvoice side and submissions will not be allowed unless it is met. The value can be used to create client-side validation to ensure that the submission form meets the requirements as defined in the configuration. It's preferred that form contain as much validation as possible before submitting. In the sample below the Review Text must be at least 50 characters.reviewtext: { default: null, value: "", maxLength: 50000, required: false, yype: "TextAreaInput", label: null, id: "reviewtext", minLength: 50 },⚠ERROR_FORM_TOO_SHORTerror will be returned from the API if a submission does not meet theMinLengthvalue.
Step 4: Submit product(s) review
By this time, the review submission form(s) should be presented to the consumer to fill out. Again, this may be a single review form or a collection of submission forms.
The significance of progressive submission is that it allows shoppers the ability to partially submit a review and then return to that review to update it up to 30 days after the initial submission. For instance, it is possible to submit a review where all the required fields are not completed, then return to that review and complete the review.
The following discussion assumes the progressive submission described below:
Product review submission forms are unique and require client-side validation that must be handled by clients.
Progressively submitting a review includes the following high level processes:
progressiveSubmit.json - Client Mastered authentication
Below details describe using a progressive submission request using Client Mastered authenticationrequest parameters
| Name | Description | Required |
|---|---|---|
format |
Data format (json) |
Yes |
Query string |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
The API version, e.g. 5.4. |
Yes |
fields |
Included to indicate that form fields, as from initiateSubmit.json request, should be returned along with the response. This parameter is sent as a single key and does not need a value. |
No |
preview |
Include this field to indicate that the API should not submit and instead return a display representation of the review. This parameter is sent as a single key and does not need a value. |
No |
Header |
||
Content-Type |
Set this to 'application/json" |
Yes |
Body |
||
productId |
A single productId for a review or review form. |
Yes |
submissionSessionToken |
Unique token ID required for progressiveSubmit.json of the review. Read more about the |
Yes |
locale |
Locale for translated product dimensions. Read more about using the |
Yes |
userToken |
Authenticated user data. Fields can instead be sent in post body. |
No |
userId |
Unique ID for user. * Can be encoded in |
Yes* |
useremail |
Email address for user. Can either be sent separately at this level, or be encoded in UserToken. |
Yes* |
deviceFingerprint |
Unique identifier for author's device. |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
submissionFields |
Key value pairs for submitted fields on submission form. Data varies per API key configurations. |
No |
POST request
POST /data/progressiveSubmit.json?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion} HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/json
X-Forwarded-For: [AuthorIPAddress]
...
{
"locale": "en_US",
"userId": "tom",
"submissionSessionToken": "[Token_Value]",
"productId":"1000001",
"useremail":"foo@bazaarvoice.com",
"submissionFields":{
"rating":"5",
"agreedtotermsandconditions":"true",
"title": "This is the title",
"reviewtext": "This is the review text. This is some more review text. This is some review text......",
"usernickname": "largeMouthBass"
}
}
progressiveSubmit.json response
{
"hasErrors": false,
"response": {
"review": {
"SendEmailAlertWhenCommented": false,
"Rating": 5,
"SubmissionTime": "2019-08-07T21:45:12.051+00:00",
"ReviewText": "this is some title this is some title this is some title this is some title this is some title this is some title this is some title",
"Title": "this is some title",
"SendEmailAlertWhenPublished": false
},
"submissionId": "h7jcqg70gil5ggqcfqs3ru7bt",
"isFormComplete": true,
"submissionSessionToken": "h3fh0cbwjgyoud7ncqtgb6nd8_eebf6f276a745e1d0323bab2e143ecf14e92f8103ea9509c3e40ebef88de1380_laoXsLeVBDQ=_v"
}
}
progressiveSubmit.json - Hosted authentication
Below details describe using a progressive submission request using Hosted authenticationrequest parameters
| Name | Description | Required |
|---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
fields |
Included to indicate that form fields, as from initiateSubmit, should be returned along with the response. This parameter is sent as a single key and does not need a value. |
No |
preview |
Included to indicate that the API should not submit and instead return a display representation of the review. Read more about correct usage. This parameter is sent as a single key and does not need a value. |
No |
hostedauth |
Indicates the action being performed, is using hosted authentication |
Yes |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productId |
A single productId for review or review form. |
Yes |
submissionSessionToken |
Unique token id required for |
Yes |
locale |
Locale for translated product dimensions. |
Yes |
userId |
Unique id for user. Can be retrieved as part of initiateSubmit response. |
Yes |
useremail |
Email address for user. Can either be sent separately at this level, or be encoded in UserToken. |
Yes* |
deviceFingerprint |
Unique identifier for author's device. |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
submissionFields |
Key value pairs for submitted fields on submission form. Data varies per API key configurations. |
No |
POST request
curl -X POST \
'http://stg.api.bazaarvoice.com/data/progressiveSubmit.json?apiVersion=5.4&action=preview&fields=true&passkey=canCClB6qhUpgE3G8bsr0idot7h3j62lNFpoEUHNIvfmg&hostedauth' \
-H 'Content-Type: application/json' \
-d '{
"locale": "en_US",
"productId": "Product1",
"userId": "zky95dwa4fagufurne8",
"submissionSessionToken": "{some_token_value}",
"submissionFields": {
"rating":"5",
"agreedtotermsandconditions": "true",
"reviewtext": "Product 1: test test test test test test test test test test test test test test test test test test test test",
"title":"Product 1: Test",
"hostedauthentication_authenticationemail": "test@test.com",
"hostedauthentication_callbackurl": "http://testcustomer.bazaarvoice.com/cburl"
}
}'
progressiveSubmit.json response
{
"hasErrors": false,
"response": {
"review": {
"SendEmailAlertWhenCommented": true,
"Rating": 5,
"SubmissionTime": "2021-09-22T06:23:00.610+00:00",
"ReviewText": "Product 1: test test test test test test test test test test test test test test test test test test test test",
"Title": "Product 1: Test",
"SendEmailAlertWhenPublished": true
},
"fieldsOrder": [
"rating",
"reviewtext",
"title",
"usernickname",
"authenticationemail",
"photourl_1",
"photocaption_1",
"photourl_2",
"photocaption_2",
"photourl_3",
"photocaption_3",
"photourl_4",
"photocaption_4",
"photourl_5",
"photocaption_5",
"photourl_6",
"photocaption_6",
"videourl_1",
"videocaption_1",
"isrecommended",
"userlocation",
"Age",
"Gender",
"BodyType",
"Quality",
"Value",
"Appearance1",
"Fit_22",
"Con",
"BestUsesFlowersGifts"
],
"fields": {
"photourl_6": {
"id": "photourl_6",
"type": "url",
"class": "photourl"
},
"videourl_1": {
"id": "videourl_1",
"type": "url",
"class": "videourl"
},
"BestUsesFlowersGifts": {
"valuesLabels": {
"AnyOccasion": "Any occasion",
"ChristmasGift": "Christmas Gift",
"BirthdayGift": "Birthday Gift",
"ThankYouAppreciation": "Thank you/Appreciation",
"GiftCorporate": "Gift Corporate",
"GiftSympathy": "Gift Sympathy",
"BasketCongratulations": "Basket Congratulations"
},
"autoPopulate": false,
"label": "Best Uses",
"id": "tagid_BestUsesFlowersGifts",
"type": "multichoice",
"class": "tag",
"required": false
},
"photourl_2": {
"id": "photourl_2",
"type": "url",
"class": "photourl"
},
"photourl_3": {
"id": "photourl_3",
"type": "url",
"class": "photourl"
},
"photourl_4": {
"id": "photourl_4",
"type": "url",
"class": "photourl"
},
"photourl_5": {
"id": "photourl_5",
"type": "url",
"class": "photourl"
},
"rating": {
"id": "rating",
"type": "integer",
"class": "rating"
},
"Gender": {
"valuesLabels": {
"Male": "Male",
"Female": "Female"
},
"autoPopulate": true,
"label": "What is your gender?",
"id": "contextdatavalue_Gender",
"type": "choice",
"class": "cdv",
"required": false
},
"BodyType": {
"valuesLabels": {
"Apple": "Apple",
"Curvy": "Curvy",
"FullFigured": "Full figured",
"Hourglass": "Hourglass",
"LongAndLean": "Long and Lean",
"PearShaped": "Pear shaped",
"Slender": "Slender",
"Petite": "Petite"
},
"autoPopulate": false,
"label": "What is your body type?",
"id": "contextdatavalue_BodyType",
"type": "choice",
"class": "cdv",
"required": false
},
"title": {
"required": false,
"hidden": false,
"id": "title",
"maxLength": 50,
"type": "text",
"class": "title"
},
"reviewtext": {
"required": false,
"hidden": false,
"id": "reviewtext",
"minLength": 50,
"type": "text",
"class": "reviewtext"
},
"isrecommended": {
"id": "isRecommended",
"type": "boolean",
"class": "isrecommended"
},
"photocaption_2": {
"id": "photocaption_2",
"type": "text",
"class": "photocaption"
},
"photocaption_1": {
"id": "photocaption_1",
"type": "text",
"class": "photocaption"
},
"Quality": {
"autoPopulate": false,
"label": "How would you rate the quality of this product?",
"id": "rating_Quality",
"type": "integer",
"class": "rating",
"required": false
},
"photocaption_6": {
"id": "photocaption_6",
"type": "text",
"class": "photocaption"
},
"authenticationemail": {
"required": true,
"hidden": false,
"id": "hostedauthentication_authenticationemail",
"type": "text",
"class": "hostedauthentication_authenticationemail"
},
"photocaption_5": {
"id": "photocaption_5",
"type": "text",
"class": "photocaption"
},
"photocaption_4": {
"id": "photocaption_4",
"type": "text",
"class": "photocaption"
},
"photourl_1": {
"id": "photourl_1",
"type": "url",
"class": "photourl"
},
"photocaption_3": {
"id": "photocaption_3",
"type": "text",
"class": "photocaption"
},
"videocaption_1": {
"id": "videocaption_1",
"type": "text",
"class": "videocaption"
},
"Age": {
"valuesLabels": {
"17orUnder": "17 or under",
"18to24": "18 to 24",
"25to34": "25 to 34",
"35to44": "35 to 44",
"45to54": "45 to 54",
"55to64": "55 to 64",
"65orOver": "65 or over"
},
"autoPopulate": true,
"label": "How old are you?",
"id": "contextdatavalue_Age",
"type": "choice",
"class": "cdv",
"required": false
},
"Con": {
"valuesLabels": {
"Bulky": "Bulky",
"Heavy": "Heavy",
"RetainsOdors": "Retains Odors",
"StainsEasily": "Stains Easily"
},
"autoPopulate": false,
"label": "Cons",
"id": "tagid_Con",
"type": "multichoice",
"class": "tag",
"required": false
},
"Appearance1": {
"autoPopulate": false,
"label": "How would you rate the appearance of the product?",
"id": "rating_Appearance1",
"type": "integer",
"class": "rating",
"required": false
},
"usernickname": {
"required": true,
"hidden": false,
"id": "usernickname",
"minLength": 4,
"type": "text",
"class": "usernickname"
},
"Value": {
"autoPopulate": false,
"label": "How would you rate the value of this product?",
"id": "rating_Value",
"type": "integer",
"class": "rating",
"required": false
},
"_Location": {
"required": false,
"hidden": false,
"id": "userlocation",
"type": "text",
"class": "userlocation"
},
"Fit_22": {
"valuesLabels": {
"valueLabel1": "Too small",
"valueLabel2": "A little small",
"valueLabel3": "True to size",
"valueLabel4": "A little big",
"valueLabel5": "Too big"
},
"autoPopulate": false,
"label": "Fit",
"id": "rating_Fit_22",
"type": "integer",
"sliderSize": 5,
"class": "slider",
"required": false
},
"useremail": {
"required": true,
"hidden": false,
"id": "useremail",
"type": "text",
"class": "useremail"
}
},
"submissionId": "{some_id}",
"submissionSessionToken": "{some_token}",
"isFormComplete": false
}
}
Additional Tips
How to avoid submitting 'ratings only' reviews
With progressive submission, it is possible to submit a 'ratings-only' review. A 'ratings-only' review is where a review contains no content other than an integer rating.
Avoid this by setting the preview flag on submission until the point where the review is ready for moderation and publication.
How to change the fieldsOrder elements
The fieldsOrder element is contained within the progressiveSubmit.json response. This element contains the suggested order of the review elements as they should be presented on a review submission form. The array of elements contained within the fieldsOrder elements are ordered by:
- Overall rating
- Review text
- Review title
- Nickname
- Required submission elements
- Location
- All other required questions as ordered in the Submission Form editor
- Photo
- Video
- Would you recommend to a friend
- Non-required fields as ordered in the Submission Form editor
If email and location are not configured as required, they are expected to appear with the non-required fields and ordered in the same way as the submission form editor.
The order of the review submission questions can be modified in the Submission Form Editor within the the site manager from the Bazaarvoice Workbench. Read more about working with the configuration hub.
What should be included in the UserToken?
The UserToken is an encoded set of fields sent in the request body that are authenticated via an HMAC generated with the client's encodingKey.
Read more about creating the UserToken. The following table details some of the values you can encode in the token:| User Token Field | Value |
|---|---|
| date | YYYYMMDD formatted date on which this token was generated |
| userid | Reviewer's unique ID. |
| emailAddress | Reviewer's email address. |
| username | Reviewer's username. |
| verifiedPurchaser | 'true' to indicate that the reviewer has been verified to have purchased the product. |
| IncentivizedReview | Indicates user has purchased item they are reviewing. Omit if value is not 'true'. |
| MaxAge | The number of days before the user authentication string expires. The default number of days is one. Changing this to a greater value is useful in preauthenticated URLs such as in email campaigns. |