Badges
This tutorial introduces developers to badges used in the Conversations API
Introduction
Bazaarvoice badges allow content and/or contributors to be recognized, or flagged, as having an additional meaning. Badges can support such concepts as 'featured' content, indicating a contributor's expertise on a product,
acknowledge incentivized content, and also top content providers. Badges are placed on user generated content (reviews, questions, answers) or on contributors. Various badge types are discussed below:
Badging types
Content-level badges
Content-level badges are tied to an individual piece of content (reviews, questions, answers), not to a contributor. The list below describes supported content-level badges:
Featured badge
If an especially rich piece of content is available, it's possible highlight it. This action is completed in the Work Bench, by denoting the content as 'featured'. 'Featured' content is returned from the API by having the IsFeatured node value of true but can also return data within the Badges node. Obtaining the "featured" Badges is completed in the implementation configurations. There is no limit to the number of content items that may be 'featured'.
A sample API response with the 'Featured' badge enabled will include:
...
BadgesOrder: [
"featured"
],
Badges: {
featured: {
BadgeType: "Custom",
Id: "featured",
ContentType: "REVIEW"
}
},
AuthorId: "4bn4ndfwf94",
SecondaryRatingsOrder: [ ],
IsFeatured: true,
....
Using the 'featured' badge it is possible to ensure end users are first presented with the specific featured content. This is accomplished using the &Sort parameter in the API request for content.
It is also possible to allow end users to filter, or view, only that content marked as 'featured'. This is possible using the &Filter parameter.
The following represents displays possibilities of 'featured' badges:
| Sample Values | |
|---|---|
| Icon |
⭐️
|
| Text | 'We really liked this!' |
Incentivized badge
FTC regulations concerning consumer-generated content, as well as the Bazaarvoice Authenticity Policies, require that reviews display a notification (either as a badge or as a displayed context data answer) 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
It is critical that this be done in a standardized way so that the incentivized notation will also syndicate to the retailer and display on their site correctly. The badging of content does not need to appear the same across syndicated sites, but must be present. Clearly identifiable graphical icons on one site and text labels on a following site is acceptable.
The Badging Reviews tutorial further details the requirements when providing consumer incentives.
| Sample Values | |
|---|---|
| Icon | |
| Text | 'This reviewer received sample product.' |
| Badge location |
|
Verified purchaser badge
The Verified purchaser badge identifies end users who have purchased products from a given client. This provides content authenticity as the person is guaranteed to have actually purchased the product.
Verified purchasers are most often indentified by targeting purchasers using Post-interaction Email (PIE). Post-interaction emails invite your customers to leave a review for a product they have purchased, a service they have
received, or any other type of interaction on your website, over the phone, or in your brick-and-mortar stores. Bazaarvoice can collect data for PIE in two ways:
- Maintenance-free PIE
- Sending PIE based on feeds
For more information on PIE please open a Bazaarvoice support ticket.
The following is a POST example where the purchaser has been verified:
ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&contextdatavalue_VerifiedPurchaser=True
When verified purchaser badges are enabled, API responses will include:
....
BadgesOrder: [
"VerifiedPurchaser"
],
Badges: {
VerifiedPurchaser: {
BadgeType: "Custom",
Id: "VerifiedPurchaser",
ContentType: "REVIEW"
}
},
....
And may include ContextDataValues if congfigured as such:
...
ContextDataValues: {
VerifiedPurchaser: {
Value: "True",
ValueLabel: "Yes",
DimensionLabel: "Verified Purchaser",
Id: "VerifiedPurchaser"
},
....
},
....
The following represents displays possibilities of 'verified purchaser' badges:
| Sample Values | |
|---|---|
| Icon | |
| Text | 'This reviewer received sample product.' |
| Badge location |
|
Best answer badge
With Best answer badges, the community can vote for the answer that it deems the “best” for a particular question. The answer, along with a combination of the most “best answer” and helpfulness votes, is awarded the best answer
badge. Badges are applied and updated dynamically, based on the current vote count.
best answer badges allow customers to easily identify high-quality content, especially as content increases in volume. This ability encourages contributors to submit more answers and high-quality answers.
During implementation you can configure the minimum number of approved answers a question must have before the "Vote as best answer" check box appears. As a result, the best answer badge can be configured so that it does not appear unless a minimum threshold is met. The thresholds for the Vote as best answer check box and the best answer badge are configured independently of each other.
Response back from the Conversations API Answers endpoint contain a boolean "IsBestAnswer", indicating if the answer is voted as the best. Using this parameter, it possible to both sort and filter the responses.
....
BadgesOrder: [
"bestAnswer"
],
Badges: {
bestAnswer: {
BadgeType: "Custom",
Id: "bestAnswer",
ContentType: "ANSWER"
}
},
....
| Sample Values | |
|---|---|
| Icon | |
| Text | 'This is the best answer!' |
Custom Contextual badges
It's possible to create custom badges for content. This allows clients to be more authentic about the content they are collecting and displaying to users. After the implementation configuration to support such data is created, a form to collect such information present to collect user feedback. Like the other data collected in the form, values are then POSTed to the Bazaarvoice API. Perhaps gender is something developers beleive warrants its own badge.
....
BadgesOrder: [
"GenderMale"
],
Badges: {
GenderMale: {
BadgeType: "Custom",
Id: "GenderMale",
ContentType: "REVIEW"
}
},
......
| Sample Values | Male |
|---|---|
| Icon | |
| Text | "- Male reviewer" |
Contributor-level badges
Bazaarvoice support three types of contributor-level badges: affiliation badges, rank badges, and merit badges. These badges are tied to a contributor, and not to a piece of content. Client's can sign into the Workbench to configure contributor-level badge options for existing user IDs using the links under Manage Contributors.
Affiliation badge
These badges are associated with any, and all, content produced by a person who is employed at the product place of origin. When someone identified as having an affiliation with a client produces content, that user is flagged with an 'affiliation badge'. Part of Bazaarvoice's Authenticity Policy requires that any relationship be disclosed.
Affiliations are not limited to the 'staff' role. Configurations support custom affiliations.
Two methods exist for indicating a contributor should display an affiliation badge:
- Within the Bazaarvoice Workbench, UserIDs and Contributor role may be added/edited via the 'Contributor Settings: Assign Contributor Roles' page.
- At login, if an end-user can be identified as 'staff' then badging can occur at the time of submission. Recall that affiliation badges are contributor specific (not content specific). For this to occur, additional parameters as part of their encoded user authentication string are required (i.e. affiliation=Staff)
Affiliation Badge will be available for both native and syndicated reviews.
- For Native reviews: Affiliation Badge is available when the Affiliation Badge on native reviews is enabled in Configuration Hub. Below is the sample response.
...
"IsSyndicated": false,
BadgesOrder: [
"Staff"
],
Badges: {
Staff: {
BadgeType: "Affiliation",
Id: "Staff",
ContentType: "REVIEW"
}
},
},
...
- For Syndicated reviews: Affiliation Badge is available when the Affiliation Badge on syndicated reviews is enabled in Configuration Hub. Below is the sample response.
...
"IsSyndicated": true,
BadgesOrder: [
"Staff"
],
Badges: {
Staff: {
BadgeType: "Affiliation",
Id: "Staff",
ContentType: "REVIEW"
}
},
},
...
Implementation TipWe recommend consulting your legal department to ensure you comply with your local regulations with respect to displaying staff reviews.
If you wish to display distinct Affiliation Badges for native and syndicated reviews, utilize the isSyndicated field to distinguish between the review types, as illustrated in the pseudocode below.
If isSyndicated = false Then display the Affiliation Badge you wish to display on your native reviews Else if isSyndicated = true Then display the Affiliation Badge you wish to display on your syndicated reviewsIf you wish to display the same Affiliation Badge on both native and syndicated reviews, then you need not make this distinction.
| Sample Values | |
|---|---|
| Icon | |
| Text | 'Staff' 'This contributor is member of the Product team.' |
| Badge Location | This badge is associated with the contribtor and should therefore reside near the user's nickname. (Image shown with ToolTip)
|
Ranking badges
A ranking badge should be used to dispaly contributors who are specialists in the products or categories. By default, the 'Expert' badge is available as a rank badge. Customization on on the rank badge name is possible. As is the
creation of a number of different ranks. For instance creating the ranks of 'platinum', 'gold', 'silver', and 'copper' is possible.
Two methods exist for indicating a contributor should display a rank badge:
-
Within the Bazaarvoice Workbench, UserIDs can be assigned an 'expert' (or custom) status. They may be added/edited via the 'Contrinbutor Settings: Assign Contributor Roles' page.
-
At login, if an end-user can be identified as an 'expert', or other custom rank, then badging can occur at the time of submission. Rank badges are contributor specific (not content specific). For this to occur, additional parameters as part of their encoded user authentication string are required (i.e. rank=Expert).
... BadgesOrder: [ "Expert" ], Badges: { Expert: { BadgeType: "Rank", Id: "Expert", ContentType: "REVIEW" } }, }, ...
| Sample Values | |
|---|---|
| Icon | |
| Text | 'Expert' 'We've noticed this contributor is usually detailed and informative.' |
| Badge Location | This badge is associated with the contribtor and should therefore reside near the user's nickname
|
Merit badges
Merit badges are automatically calculated each night and applied to contributors based on amount of content and helpfulness of their content. The following levels are available for merit badging:
- Number 1 contributor
- Top 10 contributor
- Top 25 contributor
- Top 50 contributor
- Top 100 contributor
- Top 250 contributor
- Top 500 contributor
- Top 1,000 contributor
To maintain the prestige of the merit badges, Bazaarvoice assigns a growing number of badges as a client’s distinct contributor population grows. The system has been deliberately designed to assign a merit badge to no more than
20% of a site’s contributor population.
To further increase the requirements necessary for a merit badge, an individual contributor must provide at least two approved contributions, i.e. some combination of reviews, answers, to qualify for a merit badge. This minimum contribution threshold is client configurable.
The formula to rank site contributors factors in approved reviews, approved answers (for Ask & Answer) and the helpfulness votes received.
| Sample Values | |
|---|---|
| Icon | |
| Text | 'Number 1 Contributor' 'Top 10 Contributor' 'Top 25 Contributor' 'Top 50 Contributor' 'Top 100 Contributor' 'Top 250 Contributor' 'Top 500 Contributor' 'Top 1000 Contributor' |
| Badge Location | This badge is associated with the contribtor and should therefore reside near the user's nickname
|
Prior to submission and rendering badges, your implementation must be configured to support such options. Please contact Bazaarvoice support to inquire about enabling options.
Submission
Context-level badges
Depending on the badge, data can be submitted in one of three ways. The following is a list of the submission methods as well as the badges which use them.
Context Data Value submission
These badges support API POST submission through the familiar key/value pair, with a minor caveat. The key uses the Id of the badge from the configuration but is also prefixed with "contextdatavalue_". A complete sample would look something like where the:
-
&contextdatavalue_IncentivizedReview=True -
&contextdatavalue_VerifiedPurchaser=True -
&contextdatavalue_SomeCustomBadge=100 -
Incentivized badge
-
Verified badge
-
Custom badge
Calculated or derived values
There is no submission needed in this case. Calculations are performed nightly to determine the correct content to badge.
- best answer badge
Setting up a "featured" badge is only available through Workbench. Along with indicating a particular piece of content is featured, the client configuration also must enable the featured badge.
Contributor-level badges
Of the contributor-level badges, only the affiliation and ranking badges can be submitted through the API with user generated content. Submitting contributor-level badges is done by injecting the badge type ("affiliation" or "rank") and a value ("staff" or "expert" respectively) into the User Authentication String (UAS) before encrypting and POSTING. The value for the particular badge type must exist in the client configuration prior to submitting.
Sample unencoded UAS
date=2015-10-23&userid=ID12345&affiliation=staff
You can learn more about User Authentication String from Client Mastered Authentication.
Another way to provide contributor-level with either an affiliation ("staff") or ranking ("expert") badge is through the Bazaarvoice Workbench. The knowledge base article Assign Badges describes how to complete this action.
Display
How to display badges?
Image links are not returned from the Conversations API. The display for Conversation API clients is left up to the client's creative interpretation. Bazaarvoice has several suggestions when displaying badge information returned
from the API.
- When present in the API repsonse, incentive and affiliation badges must be shown at all time. This policy is detailed in Bazaarvoice's Authenticity Policy.
- Up to three badges should be shown on a wide display. Only one badge is shown on a narrow display.
- 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 pop-over which will display on the mouseover event.
- Context-badges should be located near the user generated content (review, question, answer). Contributor-level badges should be located near the contributor indenification (nickname, username) to reinforce that this badge is on the person and not content.
Appendix
Sample API response
The following is a sample JSON response containing multiple badges. The key/values pairs are further explained below:
....
BadgesOrder: [
"top100Contributor", "Staff", "VerifiedPurchaser"
],
Badges: {
top100Contributor: {
BadgeType: "Merit",
Id: "top100Contributor",
ContentType: "REVIEW"
},
Staff: {
BadgeType: "Affiliation",
Id: "Staff",
ContentType: "REVIEW"
},
VerifiedPurchaser: {
BadgeType: "Custom",
Id: "VerifiedPurchaser",
ContentType :"REVIEW"
}
},
....
BadgesOrder element
The BadgesOrder array is a legacy element and can be ignored.
Badges Element
The subsequent child objects names and matching Ids are arguably the most important information contained in the Badges object. Individual elements are compose of several key/value pairs that further describe the badge. For
instances. the Id key/value repeats the object's name and can be to obtain the ContextDataValues (i.e. 'topContributor').
This following lists the keys/value pairs and their definitions:
BadgeType
The BadgeType lists the badge category. Values include "Merit", "Custom", "Affiliation", and "Rank". These are codes internal to Bazaarvoice.
Id
The badge Id can be used to obtain the related ContextDataValues that can also be returned in the API repsonse when configured. ContextDataValues can contain additional metadata such as a label to be displayed rather than an icon or ToolTip copy.
ContentType
The badge ContentType indicates the specific item the badge is meant for. Typical values are 'REVIEWS', 'QUESTIONS', or 'ANSWERS'.
Bazaarvoice used icons
The following is a Bazaarvoice prepared sprite sheet and may be used in client
solutions.
Including badge ID as an HTML class name
One methodology for displaying icons or text representing badges is writing the Badges Id to a class of an HTML element. A developer would be know of the configured badges and their Ids and could prepare CSS to render the correct icon or text.
// the Incentivized badge was encountered
// get the incentivized icon
.incentivized{
height: 80%;
background: url(../img/icon/incentivized.png) no-repeat;
background-size: cover;
text-align: center;
}
// or write some incentivized specific text
.incentivized::after{
content: " - Received Free Gift";
}
Updated 5 months ago