Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
iovation - web
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
This tutorial demonstrates how to create and submit device fingerprint information from iovation along with user generated content to the Bazaarvoice Conversations API.
Introduction
Mass advertising campaigns, trolling, and attempts at automated content submission are all sources of inauthentic content. To combat them Bazaarvoice has partnered with iovation, an industry leader in device reputation technology.
iovation ReputationShield™
iovation's ReputationShield™ is a JavaScript based solution that generates an encoded device fingerprint string - aka black box - containing information about the end-user's computing device such as OS, browser, etc (no PII is exchanged or maintained). This device fingerprint black box string is used in conjunction with sophisticated algorithms allowing Bazaarvoice to identify, flag and report suspicious content. Without this information our fraud detection technology will not be able to identify submissions as authentic consumer generated content.
Step-by-step Overview
The following list is a step-by-step overview of the process for collecting device information. It assumes a client side environment that supports JavaScript, such as a web browser:
- Configure and load iovation's JavaScript library in your web app.
- Wait for ioviation's script to analyze the user agent and create a device fingerprint black box string.
- Submit to the Bazaarvoice Conversations API including the fp parameter with the iovation black box value.
Continue reading to learn about the different integration options provided by ioviation and how to use them in conjunction with the Bazaarvoice Conversations API.
ReputationShield™ Website Integration
Choose one of the following integration methods to integrate iovation's ReputationShield™ in your website:
- Snare.js only:
- Include a form field with predefined ID and Name attributes and snare.js will automatically set it's value to the black box string.
- Callback function:
- Define a callback function on the page which will be called by snare.js several times indicating the availability of the black box string
- ioGetBlackBox():
- ioGetBlackBox() returns an object that that can be queried to determine if the black box string is available and the value of the string
Snare.js only
This is the easiest technique, but it offers the least flexibility. It will only work with one form on the page and the form must be on the page before snare.js is loaded.
<form action="http://yourdomain.example.com/path/to/your/service" method="post"> <!-- Your other form fields here --> <input type="hidden" name="blackBox" id="blackBox"/> </form> <!-- 1. Configure iovation's JavaScript. --> <script language="JavaScript"> // Configurations must be on page before snare.js window.io_bbout_element_id = 'blackBox', // Populate #blackBox input with device fingerprint window.io_install_stm = false, // do not install Active X window.io_exclude_stm = 12, // do not run Active X window.io_install_flash = false, // do not install Flash window.io_min_flash_version = 9999; // disable Flash window.io_enable_rip = true; // collect Real IP information </script> <!-- 2. Load snare.js from mpsnare.iesnare.com. MUST NOT BE SAVED LOCALLY --> <script src="https://mpsnare.iesnare.com/snare.js"></script>
Callback function
Somewhat more complex than Snare.js only, but provides useful information about when the black box string is available.
<form action="http://yourdomain.example.com/path/to/your/service" method="post"> <!-- Your other form fields here --> <input type="hidden" name="blackBox" id="blackBox"/> </form> <!-- 1. Configure iovation's JavaScript. --> <script language="JavaScript"> // Configurations must be on page before snare.js window.io_install_stm = false, // do not install Active X window.io_exclude_stm = 12, // do not run Active X window.io_install_flash = false, // do not install Flash window.io_min_flash_version = 9999; // disable Flash window.io_enable_rip = true; // collect Real IP information </script> <!-- 2. Define io_bb_callback(). --> <script language="JavaScript"> // io_bb_callback() will be executed as blackBox is updated // Final update will set isComplete to true // Must be on page before snare.js function io_bb_callback(blackBoxString, isComplete) { if ( isComplete ) { document.getElementById('blackBox').value = blackBoxString; } }; </script> <!-- 3. Load snare.js. MUST NOT BE SAVED LOCALLY --> <script src="https://mpsnare.iesnare.com/snare.js"></script>
ioGetBlackBox()
This method offers the most information and control however it is also the most complex because each object returned by ioGetBlackBox() is unique, so ioGetBlackBox() may need to be executed several times until the black box string is available.
<form action="http://yourdomain.example.com/path/to/your/service" method="post"> <!-- Your other form fields here --> <input type="hidden" name="blackBox" id="blackBox"/> </form> <!-- 1. Configure iovation's JavaScript. --> <script language="JavaScript"> // basic configurations must be on page before snare.js window.io_install_stm = false, // do not install Active X window.io_exclude_stm = 12, // do not run Active X window.io_install_flash = false, // do not install Flash window.io_min_flash_version = 9999; // disable Flash window.io_enable_rip = true; // collect Real IP information </script> <!-- 2. Load snare.js from mpsnare.iesnare.com. MUST NOT BE SAVED LOCALLY --> <script src="https://mpsnare.iesnare.com/snare.js"></script> <!-- 3. Each call to ioGetBlackbox() returns a JavaScript object with information about the current state of the black box and eventually the black box string itself --> <script language="JavaScript"> var timeoutId; function useBlackboxString(intervalCount) { if (typeof ioGetBlackbox !== 'function') {return;} var bbData = ioGetBlackbox(); if (bbData.finished) { clearTimeout(timeoutId); document.getElementById('blackBox').value = bbData.blackbox; } } timeoutId = setInterval(useBlackboxString, 500); </script>
Consider limiting your useBlackboxString
function to a fixed number of executions after which you assume the black box string is unavailable.
Troubleshooting
If things do not appear to be working, you can check the value of the following JavaScript variable to look for errors caught while processing.
Name | Description | Default Value |
---|---|---|
window.io_last_error |
Value is set to the last error encountered in the script. | Empty string |
Submitting device fingerprint to Bazaarvoice
The iovation device fingerprint black box string must be communicated to Bazaarvoice using the fp
parameter along with the user generated content.
Parameters
Name | Description | Default Value |
---|---|---|
fp |
Value is iovation device fingerprint black box string. | N/A |
Content types
The fp
parameter is available for the following content types.
- Review
- Review Comment
- Question
- Answer
- story
- Story Comment
Example
Submission should be performed using the HTTP POST method with a request body due to the length of the black box string and limitations imposed on query string length by some servers.
The example below shows a submission including a the fp
parameter.
POST /data/submitreview.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
…
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&fp=[BlackBoxString]
Ellipses (…) in above example indicate that your app may generate other headers.
Encoding the blackbox string
The black box string contains characters that are reserved for special purposes in a URI. For example, the plus sign (+
) is an encoding for the white space character. Because submission is performed using the Content-Type: application/x-www-form-urlencoded
header, our appliction will decode the black box string and interprete a plus sign as a white space character.
To correctly submit the black box string, you must ensure that the black box string is itself percent encoded, so that any reserved characters are not misinterpreted. For example, the percent encoding for a plus sign is %2B
. When our application encounter that sequence of characters, it will be interpreted as a +
character.
The following examples demonstrate unencoded and encoded black box strings:
Unencoded
The black box string depicted in this example should not be submitted to Bazaarvoice because it is not encoded.
0400mTR4Z7+BQcwNf94lis1ztli3mJEkJyoNdUgbrAJXB1FL4OEJMXZmD5jK1MaVRDhlAQ9qVcA9LW6vVIn0Up+4mzLLK7Xd4mGlEKa0Y+mB3pcCMqvMh8qRwB6l1hlSasV82UeoAtphovcW/PXBDOAZObSUZpybFcXAARVnJuq5mFWxH1ZPRIwM6iaikdE2N/iBS7gHh9oerxrosS1xgSAgNfLEMokGoGJxq3nJn2qrpH3U8XBpd1sDgWA73rYZtIsVyoA80pXCaXYch6NDTeqGONC1UJgA1BQZDi8R6wVNV9r6qoxEqm2gQ71/Y9e8eiB48zOQG3Lx3BMX0E/AY6vmjxNpiXJ/hZ…
Ellipses (…) indicated that the string has been shortened for demonstration purposes.
Encoded
This black box string is encoded and is safe to submit to Bazaarvoice.
0400mTR4Z7%2BBQcwNf94lis1ztli3mJEkJyoNdUgbrAJXB1FL4OEJMXZmD5jK1MaVRDhlAQ9qVcA9LW6vVIn0Up%2B4mzLLK7Xd4mGlEKa0Y%2BmB3pcCMqvMh8qRwB6l1hlSasV82UeoAtphovcW%2FPXBDOAZObSUZpybFcXAARVnJuq5mFWxH1ZPRIwM6iaikdE2N%2FiBS7gHh9oerxrosS1xgSAgNfLEMokGoGJxq3nJn2qrpH3U8XBpd1sDgWA73rYZtIsVyoA80pXCaXYch6NDTeqGONC1UJgA1BQZDi8R6wVNV9r6qoxEqm2gQ71%2FY9e8eiB48zOQG3Lx3BMX0E%2FAY6vmjxNpiXJ%2FhZ…
Ellipses (…) indicated that the string has been shortened for demonstration purposes.
Refer to the Appendix to see code examples depicting how to properly encode the black box string.
Appendix
Your device fingerprint
iovation is implemented on this page so you can see an example of a black box string. The string below is the fingerprint for your device
Loading...
Encoding code examples
Plain JavaScript
You must encode the values yourself when using plain JavaScript. Learn more about encodeURIComponent().
var title = encodeURIComponent('This is an example submission'); var blackBoxString = encodeURIComponent('0400mTR4Z7+BQcwNf94lis1ztli…'); var http = new XMLHttpRequest(); http.open('POST', 'https://developer.bazaarvoice.com/data/submitreview.json'); http.setRequestHeader('Content-type', 'application/x-www-form-urlencoded'); http.onreadystatechange = function () {…} http.send('rating=5&title=' + title + '&fp=' + blackBoxString);
jQuery
Object method
If you pass submission data as an object, jQuery will automatically encode the values for you.
var jqxhr = jQuery.ajax({ type: 'POST', url: 'https://developer.bazaarvoice.com/data/submitreview.json', data: { rating: 5, title: 'This is an example submission', fp: '0400mTR4Z7+BQcwNf94lis1ztli…' }, success: function () {…} })
String method
When passing submission data as a string, you must encode the values yourself. Learn more about encodeURIComponent().
var title = encodeURIComponent('This is an example submission') var blackBoxString = encodeURIComponent('0400mTR4Z7+BQcwNf94lis1ztli…') var jqxhr = jQuery.ajax({ type: 'POST', url: 'https://developer.bazaarvoice.com/data/submitreview.json', data: 'rating=5&title=' + title + '&fp=' + blackBoxString, success: function () {…} })