Introduction

This tutorial explains how to build feedback submission and display into your applications using the Bazaarvoice Conversations API. Readers will learn how to submit feedback via the Conversations API. The tutorial also addresses the user interface: how to handle syndicated content and also how to simulate 'real time' updating of feedback counts.

Reference documentation on feedback submission is also published on the Developer Portal

Mechanics of submission

This section describes how to submit helpfulness votes and inappropriate feedback. Helpfulness and inappropriate feedback submission follow the same process.

Helpfulness Feedback

Helpfulness Feedback Parameters

The following parameters are needed to submit helpfulness feedback:

Helpfulness Feedback Request

The sample below represents a helpfulness feedback submission request

POST /data/submitfeedback.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
X-Forwarded-For: [AuthorIPAddress]
Content-Type: application/x-www-form-urlencoded
...

ApiVersion=[latestApiVersion]&ContentType=[ContentType]&ContentId=[ContentId]&FeedbackType=helpfulness&Vote=[HelpfulnessVote]&PassKey=[yourKey]

🚧

This action must be done with an HTTPS POST

Inappropriate Feedback

Inappropriate Feedback Parameters

The following parameters are needed to submit inappropriate feedback:

Inappropriate Feedback Request

The sample below represents an inappropriate feedback submission request

POST /data/submitfeedback.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
X-Forwarded-For: [AuthorIPAddress]
Content-Type: application/x-www-form-urlencoded
...

ApiVersion=[latestApiVersion]&ContentType=[ContentType]&ContentId=[ContentId]&FeedbackType=inappropriate&PassKey=[yourKey]

🚧

This action must be done with an HTTPS POST

Handling the response

The sample below represents the response from helpfulness feedback submission.

{
    "Locale": "en_US",
    "Errors": [],
    "Feedback": {
        "Helpfulness": {
            "Vote": "POSITIVE",
            "AuthorId": "zdnjli12ey6odjql8n3zr6arlh"
        }
    },
    "Form": [],
    "FormErrors": {},
    "SubmissionId": null,
    "Data": {},
    "TypicalHoursToPost": null,
    "AuthorSubmissionToken": null,
    "HasErrors": false
}

You will need to look at the response body to determine the status of the request. This is necessary because the Conversations API always returns an HTTPS 200 code, even when an error has occurred, in order to support applications using JSONP.

The HasErrors element should be evaluated to determine success/failure of the API. Additional information on possible errors is available here.

Response elements

Specific error codes are documented in the feedback reference.

The API response to a feedback submission does not contain the current helpfulness counts. It is up to the implementation to handle tracking the current total until the next display response, which will contain the total. See the Appendix below to read about how to simulate real-time feedback counts.

Feedback User interface

Both feedback counts and feedback controls, buttons or other HTML elements that allow end-users to submit feedback, are commonly found adjacent to the content they are describing. The following image is the recommended user interface layout:

The review title, text, and rating are still the primary featured elements. Feedback counts and feedback controls are secondary. If filtering or sorting on feedback count, consider making the counts more prominent. The feedback counts provide additional context to the content. The feedback controls allow the end-user to weigh in on the content's importance.

Feedback Controls

An end-user must initiate an action to indicate a particular piece of content was note-worthy (helpful or inappropriate). Examples of this include buttons, icons, radio button, or check boxes. Any number of web controls can accomplish this.

Feedback controls may be of type helpfulness or inappropriate. These types are independent of each other. In other words, submitting one type should not disable the other type. The Limiting Users' Feedback section details this concept.

Both these types of feedback controls should only be present for the content pieces that are not syndicated. Syndicated reviews on your site cannot accept feedback. Only native reviews, those reviews collected on your site, can accept feedback. To handle this, clients should base the decision to display HTML feedback controls (such as thumbs-up/thumb-down icons) on the presence/absence of the IsSyndicated key in the review response.

Providing feedback should NOT be enabled for this content. The following is a rule emphasizing this:

• When IsSyndicated:true do NOT display the option to submit feedback.

• When IsSyndicated:false, allow end users to provide feedback.

The Syndicated Content tutorial goes into depth about this topic.

Limiting Users Feedback

The Conversations API will not limit a user from submitting feedback more than once. Also, for feedback submission, author's ID is not required. While supporting anonymous submission helps collecting content sentiment, developers will need to limit duplicate submissions in the user interface. Once a type of feedback is provided, the same type of feedback from that end-user should not be accepted.

To limit feedback, we recommend placing flags, such as cookies or local storage, after a user has submitted feedback on a specific piece of content. The existence of the flag can be use to determine if feedback should be allowed. The flag value would need to store the content ID on which feedback was provided. Two flags will be needed, one for helpfulness and one for inappropriate, since they are independent of each other. Feedback HTML controls should be disabled, or hidden, when feedback was already provided. See the sample below:

Clicking on either of the helpfulness votes above does not disable the ability to report content as inappropriate.

How to Simulate 'real-time' Feedback Counts

The Conversations API does not update feedback in real-time. The following techniques can be used to give the impression that feedback is updated in near real-time.

Helpfulness feedback

Feedback counts are part of the standard response from the Conversations API /review endpoint.

In the API response the counts appears as

...
TotalFeedbackCount: 7,
TotalNegativeFeedbackCount: 6,
TotalPositiveFeedbackCount: 1,
...

As previously discussed, these counts are often displayed with the content they represent.

First, an understanding of where helpfulness feedback counts are displayed is needed. This may be not be just on the product display pages, but also on category or other pages. Identifying the locations is needed so that feedback counts are in sync throughout the site.

Once an end user has provided helpfulness feedback the respected count should be adjusted accordingly.

After the helpfulness value updates, end-users should no longer interact with the HTML controls. The buttons below demonstrate this concept.

Click a buttons and refresh the page. The buttons remain disabled and the feedback count remains increased by one. For the purpose of this demo, two flags where set:

• A flag that captures the new helpfulness count.
• A flag that represents that the user has submitted a helpfulness vote for a given content ID.

Inappropriate feedback

Inappropriate feedback counts should not be displayed to consumers. If developing an internal application where these counts are need, please contact support.