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.

πŸ“˜

HTTP POST is required.

initiateSubmit.json

Below are the details to be used when using initiateSubmit using client mastered authentication

NameDescriptionRequired
formatData format. Set this value to "json".Yes
Query string
passkeyConversations API pass key.Yes
apiVersionThe API version, e.g. 5.4.Yes
extendedThis 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-TypeSet this value to "application/json".Yes
Body
productIdsArray of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended.Yes
UserTokenThe 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
clientUnique 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
localeLocale for contentYes
deviceFingerprintUnique identifier for author's device. Read more about deviceFingerprintNo
campaignIdCampaign 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="
      }
    }
  }
}

πŸ“˜

HTTP POST is required.

progressiveSubmit.json

Below details describe using a progressive submission request using Client Mastered authentication

Request parameters

NameDescriptionRequired
formatData format (json)Yes
Query string
passkeyConversations API pass key.Yes
apiVersionThe API version, e.g. 5.4.Yes
fieldsIncluded 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
previewInclude 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-TypeSet this to 'application/json"Yes
Body
productIdA single productId for a review or review form.Yes
submissionSessionTokenUnique token ID required for progressiveSubmit.json of the review. Read more about the submissionSessionTokenYes
localeLocale for translated product dimensions. Read more about using the locale parameter.Yes
userTokenAuthenticated user data. Fields can instead be sent in post body.No
userIdUnique ID for user. * Can be encoded in UserToken or sent as own element, depending on key configuration.Yes*
useremailEmail address for user. Can either be sent separately at this level, or be encoded in UserToken.Yes*
deviceFingerprintUnique identifier for author's device.No
campaignIdCampaign ID is a text string identifying the action that originated a piece of content. Read more.No
submissionFieldsKey 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:

  1. Overall rating
  2. Review text
  3. Review title
  4. Nickname
  5. Required submission elements
    • Email
    • Location
  6. All other required questions as ordered in the Submission Form editor
  7. Photo
  8. Video
  9. Would you recommend to a friend
  10. 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 FieldValue
dateYYYYMMDD formatted date on which this token was generated
useridReviewer's unique ID.
emailAddressReviewer's email address.
usernameReviewer's username.
verifiedPurchaser'true' to indicate that the reviewer has been verified to have purchased the product.
IncentivizedReviewIndicates user has purchased item they are reviewing. Omit if value is not 'true'.
MaxAgeThe 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.