BV-Mastered Authentication
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.
HTTPS POST is required.
initiateSubmit.json
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 fields elements are returned in an ordered list that honors the submission field order as specified in the configuration hub, with the exception that required fields are presented first in the ordered list.When included, fields elements are returned in full submission-style format. | 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 \
'https://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 HTTPS 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}"
}
}
progressiveSubmit.json
Below details describe using a progressive submission request using Hosted authentication
Request 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 progressiveSubmit of the review. Can be retrieved as part of initiateSubmit response. | 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 \
'https://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": "[email protected]",
"hostedauthentication_callbackurl": "https://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:
The UserID is an unique id that should only contain
- Alphanumeric characters, hyphens (-), and underscores (_). No other special characters should be used.
- Do not use email addresses or any other personally identifiable information for this value.
| 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. |
Depending on the passkey settings, the userid accepts plain text or encrypted text.
Updated 22 days ago