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 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:

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 identifable 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

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 'Customer has been confirmed to have purchased the item from XYZ.'
Badge Location Because the subject of the verified purchaser badge is the contributor, it is best to locate the badge near the contributor's nickname.

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.

http://stg.api.bazaarvoice.com/data/answers.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Sort=IsBestAnswer:desc

http://stg.api.bazaarvoice.com/data/answers.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=IsBestAnswer:True

                          ....
                          BadgesOrder: [
                              "bestAnswer"
                          ],
                          Badges: {
                              bestAnswer: {
                                  BadgeType: "Custom",
                                  Id: "bestAnswer",
                                  ContentType: "ANSWER"
                              }
                          },
                          ....
                          

Sample Values
Icon
Text 'This is the best answer!'

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 congfiguration 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.

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.

Affilliations 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 'Contrinbutor 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)

When affiliation badges are enabled, API responses will appear similar to:

                      ...
                      BadgesOrder: [
                          "Staff"
                      ],
                      Badges: {
                          Staff: {
                              BadgeType: "Affiliation",
                              Id: "Staff",
                              ContentType: "REVIEW"
                              }
                          },
                      },
                      ...
                      

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)

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 an 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 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, and stories, 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

Prerequisities

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 Authenication 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

Read the following tutorials to learn more about User Authentication String and 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 table 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.

Inlcuding badge ID as an HTML class name

One methodlogy 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";
                  }