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 Verified Purchaser Badges used in the Conversations API

Introduction

While you can assume that most reviewers have purchased the item(s) they are reviewing, you cannot be one hundred percent sure. Identifying individuals, who have purchased the item(s) they have written reviews on, is the purpose of the verified purchaser badge. This badge provides content authenticity because the person is more than likely to have actually purchased the product(s). This tutorial aims at helping further understand that process.

Prerequisites

Prior to submission and rendering of verified purchaser badges, your implementation must be configured to support this option. Please contact support to inquire about enabling capturing and displaying verified purchasers.

Post-interaction emails (PIE) and submission form

Upon completing an online purchase, it is common for sellers to follow up with customers to inquire about the services or items purchased. One way to accomplish this is to maintain a customer's purchase history and solicit reviews from them when they return to the site. Another way is to invite customers to leave a review for a product via email. This targeting is known as Post-interaction email (PIE).

PIE is a best practice to drive user generated content volume. PIE also contributes to UGC product coverage, content freshness, and SEO value. Clients who use PIE programs typically see more than 80% of their ratings & reviews volume generated through PIE.

The typical PIE workflow is the following: after the customer purchase the product, an email is sent. Within the email body, is a link requesting the purchaser to review the product. Once they click the link, they are taken to a form requesting a product review. This form contains a parameter indicating that the person has been identified as a verified purchaser of the product. This verified purchaser parameter is not be exposed or editable. This may be accomplished by a hidden form control, or possibly a querystring parameter in the form submission URL.

Read more about post-interaction Emails (PIE)

API submission

To complete the process of identifying a review completed by a verified purchaser, additional data must be contained within the user authentication string (UAS) on the review submission POST. This practice of submitting data to Bazaarvoice in the user authentication string instead of using the standard submission form fields is known as data injection. Typically the UAS contains identification parameters such as email or nickname, but may also contain additional pieces of information. Read more about Data injection.

In the case of Verifier Purchaser, the subjectids and verifiedpurchaser strings are necessary in the UAS. An example of an pre-encoded UAS might look like:

date=2014-01-23&userid=ID12345&verifiedpurchaser=True&subjectids=Product1/Product2/Product3

The UAS contains a single UserId and VerifiedPurchaser value, but may contain multiple subjectIds. SubjectIds are delimited by the "/" forward slash character. By supporting multiple subjectIds in the UAS, a user's purchased products history can be maintained. The subjectIds in the UAS is checked against the subjectIds of the review before presenting the verified purchaser badge.

In addition to the data encoded in the UAS, contextdatavalue_VerifiedPurchaser=True must also be contained within the POSTed review data.

Note: regardless of the Conversations API client's authentication, the verified purchaser is submitted by injecting the necessary parameters into the user authentication string and using the contextdatavalue_VerifiedPurchaser=True.
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]&PassKey=[yourKey]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&contextdatavalue_VerifiedPurchaser=True&User=6a58aac18a7770fdfff46c8da59d9270646174653d323031342d30312d3233267573657269643d494431323334352676657269666965647075726368617365723d54727565267375626a6563746964733d50726f64756374312f50726f64756374322f50726f6475637433

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

API response

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

    ....
    BadgesOrder: [
        "VerifiedPurchaser"
    ],
    Badges:{
        VerifiedPurchaser: {
            BadgeType: "Custom",
            Id: "VerifiedPurchaser",
            ContentType: "REVIEW"
        }
    },
    .....

And may include ContextDataValues if configured as such:

    .....
    ContextDataValues: {
        VerifiedPurchaser: {
            Value: "True",
            ValueLabel: "Yes",
            DimensionLabel: "Verified Purchaser",
            Id: "VerifiedPurchaser"
        },
        ....
    },

BadgesOrder element

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

Badges element

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

ContextDataValue

The ContextDataValues object and subsequent key/value pairs may offer developers additional information about the verified purchaser badge. The additional metadata associated with the verified purchaser badge can help categorize the type of review. In order to use ContextDataValues, please contact support.

Displaying verified purchaser badges

The verified purchaser badge is a contextual badge and not a contributor-level badge. The badge is related to the content (i.e. review) and should be displayed in proximity to the review.