Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
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.
In this tutorial developers will learn what it means for content to be authentic and what they can do to increase the likelihood that their applications conform to the Bazaarvoice Authenticity policy.
At Bazaarvoice we believe that authentic consumer generated content (CGC) represents the genuine, unbiased, and transparent opinion about the author’s experience with a product or service. The following is a summary of the three main characteristics of authentic CGC:
- Free from fraud and spam including disruptive or ‘trolling’ behavior, commercial messages, automated submissions (e.g. bots and scripts), content from a client’s competitor, and undisclosed self-promotion
- Free from edits, classification, and alteration by anyone other than the original author — including corrections for spelling or grammar
- We do not allow companies to directly ask for positive reviews. If consumers are offered money or promotional material (such as discounts or coupons) in exchange for providing an unbiased review, then the review must note this fact. Further, employees and vendors of the organization may not submit content without disclosing their relationship to the product or service
Refer to our Authenticity Policy to learn more about the requirements for content to be considered authentic.
Continue reading to learn how you can increase the likelihood that content submitted to our platform is authentic.
Submission access control
To be considered authentic, content cannot be submitted to a Bazaarvoice client's website by a competitor of that client. Attempts to change the aggregate rating and/or sentiment of content on another website are also considered inauthentic. Take the following submission access controls to protect against these scenarios:
API key management
Content may not be submitted to the Bazaarvoice platform using the Conversations API without an API key. We provide a self-service process allowing our clients to control who is issued active keys, as well as enable and disable keys at anytime. This gives our clients control over the applications that may submit content.
Read the self-service API key process documentation for more information.
Authentication is a way to verify that a content author is who they claim to be. The Conversations API supports two authentication methods: Bazaarvoice-mastered and Client-mastered. By implementing one of these methods, you ensure that each author is identified uniquely, making fraudulent submissions more difficult to perform and easier to catch.
Read the authentication documentation for more information.
Device reputation management
Mass advertising campaigns, trolling, and attempts at automated content submission are all sources of inauthentic content. To combat them Bazaarvoice has partnered with industry leaders in device reputation management.
Bazaarvoice uses information about the author's device, including IP address and device fingerprint, in conjunction with sophisticated algorithms allowing us to identify, flag and report suspicious content.
Author IP address
The IP address of a computer initiating an HTTP request (the client) is automatically communicated to the computer receiving the request (the server). If your Conversations API submissions originate from a web browser or mobile app, we will automatically receive the author's IP address.
However, if you are performing the submission from your server to our server, then you must use the
X-Forwarded-For header to communicate the author's IP address to us. Otherwise, we will receive your server's IP address for every submission, which increases the likelihood that your submissions will be flagged as inauthentic.
In the following example, the IP address
192.0.2.1 represents the IP address of the content author:
POST /data/submitreview.json HTTP/1.1 Host: stg.api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: 192.0.2.1 ... rating=5&title=This+is+a+review+title&reviewtext=This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+&UserNickname=bvtester&productId=io_bb_callback&userId=1234567&apiversion=5.4&action=submit&passkey=hk5pv3pfasrrdjyq487m699s
Ellipses (...) in above example indicate that your app may generate other headers.
A device fingerprint is an encoded string containing information about a user agent. The technique for generating a device fingerprint varies based on environment and device reputation partner, but in general will involve the following steps:
- Configure and load a device fingerprint library in your app.
- Wait for the script to analyze the user agent and create a device fingerprint.
- Communicate the device fingerprint to Bazaarvoice or one of our reputation management partners.
Read Device Fingerprinting for more information and code samples demonstrating how to perform device fingerprinting.
Content XML import
Bazaarvoice can import "legacy" content that was collected prior to a contractual relationship with us. This is accomplished by transforming that content into a Bazaarvoice native XML format. This format ensures that the content is properly tagged and identified in a way that is consistent with our platform's architectural requirements. This is the only way to ensure that the data required by our Authenticity Policy is properly imported.
Several example XML files demonstrating our native XML format can be seen at http://knowledge.bazaarvoice.com/wp-content/conversations/en_US/Collect/native_content_import.html#full-feed-examples.
New clients will work with their Bazaarvoice Implementation Team to perform the transform and import. Existing clients can contact our Support Team for assistance.
Text or graphic based relationship indicator
Self-promotion of products and services, endorsements, and third party content must all be clearly identified to be considered authentic. The relationship between a content author and the subject of the content should be clearly disclosed to readers. For example, a graphic badge may indicate that the author of a review is an employee of the company that manufactures the product being reviewed, or a text string could indicate that the author of the review participated in a promotion that included writing the review.
Indicating author / subject relationships can be accomplished using the Conversations API in several ways:
Badging: Badges are typically displayed as a visual symbol indicating a relationship between a content author and the content subject.
Context data values: Context data values provide additional information to users regarding the authors relationship to the subject of the content.
Refer to the following resources for additional documentation on this subject:
Users should be given the option to view CGC displayed in chronological order.
Using the Conversations API it is possible to request content pre-sorted in several ways including by submission time. The format for this is demonstrated below and is available for all Bazaarvoice content types:
|Sort suffix||Display order|
Refer to the sorting section of Display Fundamentals for more details.