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).
Updated 10 months ago