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

(+ show- hide)

This tutorial introduces developers to incentivized badges and incentivized review count in the Conversations API.

Introduction

Authenticity is a core value at Bazaarvoice. This means indicating, or badging, user generated content (UGC) where the author has been offered an incentive. FTC regulations concerning consumer-generated content, as well as the Bazaarvoice Authenticity Policy, require that reviews display a notification (either as a graphic badge or plain text) any time the consumer has received or been offered material compensation for writing their review. This includes, but is not limited to, any of the following being provided to the consumer in exchange for writing a review:

  • Entry into a sweepstakes
  • Coupons or Discounts
  • Loyalty Reward Points
  • Free products, either before as in a Sampling program or after, as a Thank You gift

In addition to badging incentivized reviews, you can display the count of incentivized reviews for each product or author, which may be required depending on local regulations. This count is referred to as the incentivized review count.

Prerequisites

Prior to submission and rendering incentivized badges, your implementation must be configured to support such options. Please contact support to inquire about enabling this option.

Submission form

There are different paths clients implementing submission forms can take when soliciting content with regards to incentivized reviews:

  • Create a dedicated incentivized submission form that indicates that the content author has been incentivized. This form would only be shared to those incentivized individuals.
  • Another possibility it to include a parameter in the link to the submission form that toggles an 'incentivized' value. (i.e. "http://example.com/products?productId=XYZ&IncentivizedReview=True”). An HTML element could then be populated accordingly. The element may be hidden on the form or exposed. This method supports the creation of a single form handling both regular submission as well as those completed by individuals who have been incentivized.

API submission post

When the author completes the submission form, the data is then submitted to the Bazaarvoice platform. The sample below is of submitting an incentivized review. Notice the “contextdatavalue_IncentivizedReview=True” included in the submission to the Bazaarvoice API.

This example is for full submission. If you are using progressive submission, the code will be different.
POST /data/submitreview.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...

ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&contextdatavalue_IncentivizedReview=True
    

Ellipses (...) in above example indicate that your app may generate other headers.

Additional tutorials on Conversations API submission are available:

It is helpful to also include the campaign ID parameter when submitting incentivized reviews to Bazaarvoice. This can indicate the source of this review and the offer that was made (i.e. “Sweepstakes”, “10pctCoupon”, etc.)

API response

When requesting content from the Conversation API (i.e. the reviews display endpoint), incentivized review data will appear as the following:

        .....
        ContextDataValues: {
            IncentivizedReview: {
                Value: "True",
                ValueLabel: "Yes",
                DimensionLabel: "Received free product",
                Id: "IncentivizedReview"
            }
        },
        BadgesOrder: [
            "incentivized"
        ],
        Badges:{
            incentivizedReview: {
                BadgeType: "Custom",
                Id: "incentivizedReview",
                ContentType: "REVIEW"
            }
        },
        .....
    

Context data values

The ContextDataValues object and subsequent key/value pairs may offer developers additional information about the incentivized review. The additional metadata associated with the incentivized review can help categorize the type of review. For example, the DimensionLabel key/value can be used to distinguish between other types of incentives and also be displayed as a label. In order to use ContextDataValues, please contact support.

BadgesOrder element

The BadgesOrder array is a legacy element and can be ignored.

Badges element

The Badges object contains the badge name ('incentivizedReview'), id, the badge type ("Custom"), and the type of content associated with the badge (reviews, question, answers).

Displaying incentivized review badges

How Incentivized Review badges are displayed for Conversation API clients is left up to creative interpretation. Bazaarvoice has several suggestions when displaying badge information.

  • Incentivized reviews must always be identified.
  • Icons or text can either be used. In the case where icons are used, the meaning or definition should be easily available. This could mean including alt text, implementing a tooltip, or popover which will display on the mouseover event.

The badging of content does not need to appear the same across syndicated sites, but must be present. For example, graphical icons on the origin site and text labels on the destination site is acceptable.

The following examples demonstrate several ways to display badges:

Syndicated incentivized reviews

Syndication occurs when reviews are collected at one site and shared to another for display. The site where the reviews were collected is the 'origin' and the site where the reviews are shared is the 'destination'. A single destination may display syndicated reviews from many origin sites. Learn more about Bazaarvoice syndication.

Identifing incentivized reviews is requried by the Bazaarvoice Authenticity policy and failure to do so may also be a violation of local law. Furthermore, syndicated incentivised reviews must not be marked with the destionation sites' promotional badging, because this creates the false impression that the syndicated content was incentivized by the destination.

Badging incentivized syndicated content

Bazaarvoice may restrict access to syndicated content due to failure to properly identify incentivized syndicated reviews.

To assist destination sites in properly identifying syndicated incentivised reviews, Bazaarvoice will automatically append text to syndicted incentivised reviews that identifies them as being part of a promotion.

A syndicated review is identified by the IsSyndicated property with a value of true in the API response, along with a SyndicationSource property identifying the origin of the review. If the syndicated review was incentivised at the origin, it will also have text appended to the review text identifying it as being part of a promotion.

    ...
    "IsFeatured": false,
    "IsSyndicated": true,
    ...
    "SyndicationSource": {
        Name: "Some Product Sampling Community",
        LogoImageUrl: "https://some/Image/Url/image.jpg",
        ContentLink: "https://some/Product/Url"
    },
    ...
    "ReviewText": "Lorem ipsum dolor sit amet, consectetur adipiscing
    elit, sed do eiusmod tempor incididunt ut labore et dolore magna
    aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
     [This review was collected as part of a promotion.]"

Take the following steps to ensure that syndicated incentivised reviews are displayed correctly:

  • Check for the isSyndicated key. If it exists and it's value is true, then do not badge that content as if it originated from your site.
  • Do not alter or remove the text added by Bazaarvoice indicating the content was part of a promotion.
  • Disclose the review source using the data available in the SyndicationSource node reference above.

Displaying the incentivized review count

The Conversations API returns the count of incentivized reviews for each product or author. Use this count to show consumers how many of the reviews for a product or written by an author have been incentivized through a sweepstakes, coupon, sampling program, etc. Bazaarvoice considers a review incentivized if it was marked as an incentivized review during submission, as detailed in prior sections of this topic, or if the review content indicates an incentive was present.

Use the incentivized review count to:

  • Show consumers a badge or informational message that highlights the count of incentivized reviews for a product.
  • Increase consumer trust in your business.
  • Comply with global consumer laws and regulations.

The following image demonstrates how you can display the incentivized review count beneath a ratings display.

Based on our user experience research and authenticity compliance guidelines, Bazaarvoice recommends using the following text to describe the incentivized review count:

incentivized review count of total review count reviewers received a sample product or took part in a promotion

Usage details

To retrieve this count, include the IncentivizedStats=true parameter in requests to resources that support it. The IncentivizedStats parameter must be used in conjunction with other parameters so that statistics are returned for products or authors in the response. The following table provides the usage details:

Conversations resource PRR resource Additional parameters required
Reviews Reviews Include=Products or Include=Authors

AND

Stats=Reviews and/or FilteredStats=Reviews
Products Products Stats=Reviews and/or FilteredStats=Reviews
Authors Authors Stats=Reviews and/or FilteredStats=Reviews
Statistics N/A Stats=Reviews, Stats=NativeReviews, or Stats=Reviews,NativeReviews

The incentivized review count displays in the IncentivizedReviewCount element returned in the statistics object of each product or author in the response.

Example

The following request retrieves reviews with an incentivized review count for each product:

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Sort=Rating:desc&Limit=10&Include=Products&IncentivizedStats=true&Stats=Reviews&FilteredStats=Reviews

For each product returned in the response, the incentivized review count displays in the following format:

    .....
    ReviewStatistics: {
        IncentivizedReviewCount: 15
    },
    .....
    FilteredReviewStatistics:{
        IncentivizedReviewCount: 10
    },
    .....