Incentivized Reviews

This tutorial introduces developers to incentivized badges and incentivized review count in the iOS SDK.

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.

Displaying incentivized review badges

How Incentivized Review badges are displayed for iOS SDK 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:

Icon only

Text only

Icon and text

Icon and tooltip

Displaying the incentivized review count

The iOS SDK 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 incentivized review data, set the property incentivizedStats=true in the Objective-C SDK and call the method incentivizedStats(true) in the Swift SDK. Use these approaches in conjunction with other parameters as described below in order to return the needed data.

Products

Objective-C SDK

Request incentivized statistics for products in bulk

BVBulkProductRequest *request = [[[[BVBulkProductRequest alloc] init]
    includeStatistics:BVProductIncludeTypeValueReviews] // include review statistics
    addCustomDisplayParameter:@"filteredstats" withValue:@"reviews"]; // added to request for filtered statistics
 
request.incentivizedStats = YES; // set this property to request for incentivized reviews data
 
[request load:^(BVBulkProductResponse * _Nonnull response) {
    for (BVProduct *product in response.results) {
        NSNumber *incentivizedReviewCount = product.reviewStatistics.incentivizedReviewCount; // incentivizedReviewCount for the product
        BVDistributionElement *incentivizedReview = [product.reviewStatistics.contextDataDistribution valueForKey:@"IncentivizedReview"];
 
        if (incentivizedReview != nil) {
            // check for the context data distribution properties using incentivizedReview object
        }
 
    }
} failure:^(NSArray<NSError *> * _Nonnull errors) {
    // handle errors
}];
let request = BVBulkProductRequest()
    .includeStatistics(.reviews) // include review statistics
    .addCustomDisplayParameter("filteredstats", withValue: "reviews") // added to request for filtered statistics
 
request.incentivizedStats = true // set this property to request for incentivized reviews data
 
request.load({ (response) in
    for product in response.results {
        let incentivizedReviewCount = product.reviewStatistics?.incentivizedReviewCount // incentivizedReviewCount of the product
 
        if let incentivizedReview = product.reviewStatistics?.contextDataDistribution?.value(forKey: "IncentivizedReview") as? BVDistributionElement {
            // check for the context data distribution properties using incentivizedReview object
        }
    }
}) { (errors) in
    // handle errors
}

Request incentivized statistics for Product Detail Pages

BVProductDisplayPageRequest *request = [[[[BVProductDisplayPageRequest alloc] initWithProductId:@"productId"]
    includeStatistics:BVProductIncludeTypeValueReviews] // include review statistics
    addCustomDisplayParameter:@"filteredstats" withValue:@"reviews"]; // added to request for filtered statistics
 
request.incentivizedStats = YES; // set this property to request for incentivized reviews data
 
[request load:^(BVProductsResponse * _Nonnull response) {
    NSNumber *incentivizedReviewCount = response.result.reviewStatistics.incentivizedReviewCount; // incentivizedReviewCount for the product
     
    BVDistributionElement *incentivizedReview = [response.result.reviewStatistics.contextDataDistribution valueForKey:@"IncentivizedReview"];
 
    if (incentivizedReview != nil) {
        // check for the context data distribution properties using incentivizedReview object
    }
} failure:^(NSArray<NSError *> * _Nonnull errors) {
    // handle errors
}];

let request = BVProductDisplayPageRequest(productId: "productId")
    .includeStatistics(.reviews) // include review statistics
    .addCustomDisplayParameter("filteredstats", withValue: "reviews") // added to request for filtered statistics
 
request.incentivizedStats = true // set this property to request for incentivized reviews data
 
request.load({ (response) in
    let incentivizedReviewCount = response.result?.reviewStatistics?.incentivizedReviewCount // incentivizedReviewCount of the product
 
    if let incentivizedReview = response.result?.reviewStatistics?.contextDataDistribution?.value(forKey: "IncentivizedReview") as? BVDistributionElement {
        // check for the context data distribution properties using incentivizedReview object
    }
}) { (errors) in
    // handle errors
}

Request incentivized statistics for product text searches

BVProductTextSearchRequest *request = [[[[BVProductTextSearchRequest alloc] initWithSearchText:@"search text"]
    includeStatistics:BVProductIncludeTypeValueReviews] // include review statistics
    addCustomDisplayParameter:@"filteredstats" withValue:@"reviews"]; // added to request for filtered statistics
 
request.incentivizedStats = YES; // set this property to request for incentivized reviews data
 
[request load:^(BVBulkProductResponse * _Nonnull response) {
    for (BVProduct *product in response.results) {
        NSNumber *incentivizedReviewCount = product.reviewStatistics.incentivizedReviewCount; // incentivizedReviewCount for the product
        BVDistributionElement *incentivizedReview = [product.reviewStatistics.contextDataDistribution valueForKey:@"IncentivizedReview"];
 
        if (incentivizedReview != nil) {
            // check for the context data distribution properties using incentivizedReview object
        }
    }
} failure:^(NSArray<NSError *> * _Nonnull errors) {
    // handle errors
}];
let request = BVProductTextSearchRequest(searchText: "search text")
    .includeStatistics(.reviews) // include review statistics
    .addCustomDisplayParameter("filteredstats", withValue: "reviews") // added to request for filtered statistics
 
request.incentivizedStats = true // set this property to request for incentivized reviews data
 
request.load({ (response) in
    for product in response.results {
        let incentivizedReviewCount = product.reviewStatistics?.incentivizedReviewCount // incentivizedReviewCount of the product
 
        if let incentivizedReview = product.reviewStatistics?.contextDataDistribution?.value(forKey: "IncentivizedReview") as? BVDistributionElement {
            // check for the context data distribution properties using incentivizedReview object
        }
    }
}) { (errors) in
    // handle errors
}
#

Swift SDK

Request incentivized statistics for products in bulk

let productQuery = BVProductsQuery(productIds: ["productid1", " productid2", " productid3"])!
    .stats(.reviews) // include review statistics
    .filter(.reviews) //request for filtered statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler { (response: BVConversationsQueryResponse<BVProduct>) in
 
    if case .failure(let error) = response { //error
        return
    }
 
    guard case let .success(_, products) = response else {
        return
    }
 
    // success
 
    for product in products {
        (product.reviewStatistics?.incentivizedReviewCount) // incentivizedReviewCount for the product
 
        if let incentivizedReview = product.reviewStatistics?.contextDataDistribution?.first(where: {$0.distibutionElementId == "IncentivizedReview"}) {
            // check for the context data distribution properties using incentivizedReview object
        }
    }
}
 
guard let req = productQuery.request else {
    return
}
 
productQuery.async(urlSession: URLSession(configuration: .default))

Request incentivized statistics for Product Detail Pages

let productQuery = BVProductQuery(productId: "productId")
    .stats(.reviews) // include review statistics
    .filter(.reviews) //request for filtered statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler { (response: BVConversationsQueryResponse<BVProduct>) in
 
    if case .failure(let error) = response {
        // error
        return
    }
 
    guard case let .success(_, products) = response else {
        return
    } // success
 
    for product in products {
        (product.reviewStatistics?.incentivizedReviewCount) // incentivizedReviewCount for the product
            if let incentivizedReview = product.reviewStatistics?.contextDataDistribution?.first(where: {$0.distibutionElementId == "IncentivizedReview"}) {
                // check for the context data distribution properties using incentivizedReview object
            }
    }
}
 
guard let req = productQuery.request else {
    return
}
 
productQuery.async(urlSession: URLSession(configuration: .default))

Request incentivized statistics for product text searches

let productQuery = BVProductSearchQuery(searchQuery: "Search text")
    .stats(.reviews) // include review statistics
    .filter(.reviews) //request for filtered statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler { (response: BVConversationsQueryResponse<BVProduct>) in
 
    if case .failure(let error) = response {
        // error
        return
    }
 
    guard case let .success(_, products) = response else {
        return
    }
 
    // success
 
    // incentivized stats
 
    for product in products {
        (product.reviewStatistics?.incentivizedReviewCount) // incentivizedReviewCount for the product
            if let incentivizedReview = product.reviewStatistics?.contextDataDistribution?.first(where: {$0.distibutionElementId == "IncentivizedReview"}) {
                // check for the context data distribution properties using incentivizedReview object
            }
    }
}
 
guard let req = productQuery.request else {
    return
}
 
productQuery.async(urlSession: URLSession(configuration: .default))

Reviews

Objective-C SDK

Request incentivized statistics for reviews

BVReviewsRequest *request = [[[[[BVReviewsRequest alloc] initWithProductId:@"productId" limit:limit offset:offset]
    includeReviewIncludeTypeValue:(BVReviewIncludeTypeValueReviewProducts)] // additional parameters to include products in response
    includeReviewIncludeTypeValue:(BVReviewIncludeTypeValueReviewAuthors)] // additional parameters to include authors in response
    addCustomDisplayParameter:@"filteredstats" withValue:@"reviews"]; // added to request for filtered statistics
 
request.incentivizedStats = YES; // set this property to request for incentivized reviews data
 
[request load:^(BVReviewsResponse * _Nonnull response) {
     
    for (BVReview *review in response.results) {
        NSNumber *incentivizedReviewCount = review.author.reviewStatistics.incentivizedReviewCount; // check for incentivizedReviewCount of author's reviewStatistics
 
        for (BVBadge *badge in review.badges) {
 
            if([badge.identifier isEqualToString: @"incentivizedReview"]) {
                // the review contains "incentivizedReview" badge, check for the properties
            }
        }
 
        for (BVContextDataValue *contextDataValue in review.contextDataValues) {
 
            if([contextDataValue.identifier isEqualToString: @"IncentivizedReview"]) {
                // check for the context data value properties of the incentivized review using contextDataValue object
            }
        }
    }
 
    BVProduct *product = response.results.firstObject.product;
 
    NSNumber *incentivizedReviewCount = product.reviewStatistics.incentivizedReviewCount; // check for incentivizedReviewCount of product reviewStatistics
 
} failure:^(NSArray<NSError *> * _Nonnull errors) {
    // handle failure
}];

let request = BVReviewsRequest(productId: "productId", limit: limit, offset: offset)
    .include(.reviewProducts) // additional parameters to include products in response
    .include(.reviewAuthors) // additional parameters to include authors in response
    .addCustomDisplayParameter("filteredstats", withValue: "reviews") // added to request for filtered statistics
 
request.incentivizedStats = true // set this property to request for incentivized reviews data
 
request.load({ (response) in
    if let product : BVProduct = response.results.first?.product {
        let incentivizedReviewCount = product.reviewStatistics?.incentivizedReviewCount // check for incentivizedReviewCount of product reviewStatistics
    }
 
    for review in response.results {
        let incentivizedReviewCount = review.author?.reviewStatistics?.incentivizedReviewCount // check for incentivizedReviewCount of author's reviewStatistics
 
        if let incentivizedBadge = review.badges.first(where: { $0.identifier == "incentivizedReview"}) {
            // the review contains "incentivizedReview" badge, check for the properties using incentivizedBadge object
        }
 
        if let contextDataValue = review.contextDataValues.first(where: {$0.identifier == "IncentivizedReview"}) {
            // check for the context data value properties using contextDataValue object
        }
    }
}) { (errors) in
    // handle errors
}
#

Swift SDK

Request incentivized statistics for reviews

let reviewQuery = BVReviewQuery(productId: “productId”, limit: limit, offset: offset)
    .include(.authors)
    .include(.products)
    .stats(.reviews)
    .filter(.reviews) //request for filtered statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler { (response: BVConversationsQueryResponse<BVReview>) in
 
    if case .failure(let error) = response {
        // error
        return
    }
 
    guard case let .success(_, reviews) = response else {
        return
    }
 
    // success
 
    for review in reviews {
        // Review Statistics
        review.products?.first?.reviewStatistics?.incentivizedReviewCount
 
        if let reviewStatistics = review.products?.first?.reviewStatistics?.contextDataDistribution?.first(where: { $0.distibutionElementId == "IncentivizedReview" }) {
            // check for the context data distribution properties using incentivizedReview object
        }
 
        // Filtered Review Statistics
        review.products?.first?.filteredReviewStatistics?.incentivizedReviewCount
 
        if let filteredReviewStatistics = review.products?.first?.filteredReviewStatistics?.contextDataDistribution?.first(where: { $0.distibutionElementId == "IncentivizedReview" }) {
            // check for the context data distribution properties using incentivizedReview object
        }
 
        if let incentivizedBadge = review.badges?.first(where: { $0.badgeId == "incentivizedReview"}) {
            // check for Incentivized review badge properties
 
            incentivizedBadge.badgeType // check for badge Type
            incentivizedBadge.contentType // check for content Type
        }
 
        // check for Context data values of incentivized review
        if let incentivizedContextDataValue = review.contextDataValues!.first(where: {$0.contextDataValueId == "IncentivizedReview"}) {
            incentivizedContextDataValue.dimensionLabel // check for incentivized Context dimension Label
            incentivizedContextDataValue.value // check for incentivized Context value
            incentivizedContextDataValue.valueLabel // check for incentivized Context value Label
        }
    }
}
 
guard let req = reviewQuery.request else {
    return
}
 
reviewQuery.async()

Request incentivized statistics for review searches

let reviewQuery = BVReviewSearchQuery(productId: “productId”, searchQuery: "Search text")
    .include(.authors)
    .include(.products)
    .stats(.reviews) // include review statistics
    .filter(.reviews) //request for filtered statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler { (response: BVConversationsQueryResponse<BVReview>) in
 
    if case .failure(let error) = response {
        // error
        return
    }
 
    guard case let .success(_, reviews) = response else {
        return
    }
 
    // success
 
    for review in reviews {
 
        // Review Statistics
        review.products?.first?.reviewStatistics?.incentivizedReviewCount
 
        if let reviewStatistics = review.products?.first?.reviewStatistics?.contextDataDistribution?.first(where: { $0.distibutionElementId == "IncentivizedReview" }) {
            // check for the context data distribution properties using incentivizedReview object
        }
 
        // Filtered Review Statistics
        review.products?.first?.filteredReviewStatistics?.incentivizedReviewCount
 
        if let filteredReviewStatistics = review.products?.first?.filteredReviewStatistics?.contextDataDistribution?.first(where: { $0.distibutionElementId == "IncentivizedReview" }) {
            // check for the context data distribution properties using incentivizedReview object
        }
 
        if let incentivizedBadge = review.badges?.first(where: { $0.badgeId == "incentivizedReview"}) {
            // check for Incentivized review badge properties
            incentivizedBadge.badgeType // check for badge Type
            incentivizedBadge.contentType // check for content Type
        }
 
        // check for Context data values of incentivized review
        if let incentivizedContextDataValue = review.contextDataValues!.first(where: {$0.contextDataValueId == "IncentivizedReview"}) {
            incentivizedContextDataValue.dimensionLabel // check for incentivized Context dimension Label
            incentivizedContextDataValue.value // check for incentivized Context value
            incentivizedContextDataValue.valueLabel // check for incentivized Context value Label
        }
    }
}
 
guard let req = reviewQuery.request else {
    return
}
 
reviewQuery.async()

Bulk Ratings

Objective-C SDK

Request incentivized statistics for bulk ratings

BVBulkRatingsRequest *request = [[[BVBulkRatingsRequest alloc] initWithProductIds:@[@"product1", @"product2"] statistics:BVBulkRatingIncludeTypeValueBulkRatingAll]
    filterOnBulkRatingFilterValue:BVBulkRatingFilterValueBulkRatingContentLocale
    relationalFilterOperatorValue:BVRelationalFilterOperatorValueEqualTo
    values:@[@"en_US"]];
 
request.incentivizedStats = YES; // set this property to request for incentivized reviews data
 
[request load:^(BVBulkRatingsResponse * _Nonnull response) {
    for (BVProductStatistics *productStats in response.results) {
        NSNumber *incentivizedReviewCount = productStats.reviewStatistics.incentivizedReviewCount; // check for incentivizedReviewCount of author's reviewStatistics
        NSNumber *nativeStatisticsIncentivizedReviewCount = productStats.reviewStatistics.incentivizedReviewCount; // check for incentivizedReviewCount of author's reviewStatistics
    }
} failure:^(NSArray<NSError *> * _Nonnull errors) {
    // handle failure
}];

let request = BVBulkRatingsRequest(productIds: ["product1", "product2"], statistics: .bulkRatingAll)
    .filter(on: .bulkRatingContentLocale, relationalFilterOperatorValue: .equalTo, values: ["en_US"])
 
request.incentivizedStats = true // set this property to request for incentivized reviews data
 
request.load({ (response) in
    for productStats in response.results {
        let incentivizedReviewCount = productStats.reviewStatistics?.incentivizedReviewCount // review statistics incentivizedReviewCount
        let nativeStatisticsIncentivizedReviewCount = productStats.nativeReviewStatistics?.incentivizedReviewCount // native review statistics incentivizedReviewCount
    }
}) { (errors) in
    // handle errors
}

Swift SDK

Request incentivized statistics for bulk ratings

let usLocale: Locale = Locale(identifier: "en_US")
 
guard let productStatisticsQuery = BVProductStatisticsQuery(productIds: ["productId"]) else {
    return
}
 
productStatisticsQuery
    .filter((.contentLocale(usLocale), .equalTo))
    .stats(.nativeReviews) // include native Reviews statistics
    .stats(.reviews) // include review statistics
    .incentivizedStats(true) // set this property to request for incentivized reviews data
    .configure(Configuration)
    .handler {
 
        (response: BVConversationsQueryResponse<BVProductStatistics>) in
 
        if case .failure(let error) = response {
            // error
            return
        }
 
        guard case let .success(_, response) = response else {
            return
        }
 
        // success
 
        for productStats in response {
            (productStats.reviewStatistics?.incentivizedReviewCount) // incentivizedReviewCount for the product
        }
    }
 
guard let req = productStatisticsQuery.request else {
    return
}
 
productStatisticsQuery.async()

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.

Badges

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