Client Mastered Authentication
Overview
In this authentication type, user IDs come from your authentication system, which is considered to be the authoritative (master) source for user identification.
HTTPS POST is required.
initiateSubmit.json
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 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 |
| 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. Depending on the passkey settings, the userid accepts plain text or encrypted text. | client |
| client | Unique id for user. Can either be sent separately 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 | 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
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 HTTPS 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="
}
}
}
}
HTTPS POST is required.
progressiveSubmit.json
Below details describe using a progressive submission request using Client Mastered authentication
Request 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 submissionSessionToken | Yes |
locale | Locale for translated product dimensions. Read more about using the locale parameter. | Yes |
userToken | Authenticated user data. Fields can instead be sent in post body. | No |
userId | Unique ID for user. Can be encoded in UserToken or sent as own element, depending on passkey configuration. | 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":"[email protected]",
"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"
}
}
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 pre authenticated URLs such as in email campaigns. |
Updated 22 days ago