❗️

Bazaarvoice clients and partners only. All others should refer to iovation for documentation.

🚧

This version of iovation's integration is not the newest. Please refer to the latest version.

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.

🚧

Per the Bazaarvoice Authenticity Policy, you must send a device fingerprint attached to each submission. If you fail to send a device fingerprint with your submission, Bazaarvoice may take any action deemed necessary in Bazaarvoice’s sole discretion to protect the integrity of the network. Such actions may include but are not limited to: rejection of your content, halting syndication of your content on the Bazaarvoice network, revocation of your API key, or revocation of your API license.

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:

1. Configure and load iovation's JavaScript library in your web app.
2. Wait for ioviation's script to analyze the user agent and create a device fingerprint black box string.
3. 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

🚧

The following are simplified examples for educational purposes. Your implementation may vary.

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>

🚧

The io_bb_callback() function may generate several black box strings in rapid succession. Each string will contain more device fingerprinting information than the last. When the user submits their content, you should use the most recently generated blackbox string.

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.

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

Content types

The fp parameter is available for the following content types.

• Review
• Review Comment
• Question
• Answer

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

❗️

Failure to correctly encode the black box string will result in your content being considered inauthentic.

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+4mzLLK7Xd4mGlEKa0
Y+mB3pcCMqvMh8qRwB6l1hlSasV82UeoAtphovcW/PXBDOAZObSUZpybFcXAARVnJuq5mFWxH1ZPRIwM6iaikdE2N/iBS7gHh9oerxro
sS1xgSAgNfLEMokGoGJxq3nJn2qrpH3U8XBpd1sDgWA73rYZtIsVyoA80pXCaXYch6NDTeqGONC1UJgA1BQZDi8R6wVNV9r6qoxEqm2g
Q71Y9e8eiB48zOQG3Lx3BMX0E/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%2B4mzLLK7Xd4mGl
EKa0Y%2BmB3pcCMqvMh8qRwB6l1hlSasV82UeoAtphovcW%2FPXBDOAZObSUZpybFcXAARVnJuq5mFWxH1ZPRIwM6iaikdE2N%2FiBS7
gHh9oerxrosS1xgSAgNfLEMokGoGJxq3nJn2qrpH3U8XBpd1sDgWA73rYZtIsVyoA80pXCaXYch6NDTeqGONC1UJgA1BQZDi8R6wVNV9
r6qoxEqm2gQ71%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

0400bpNfiPCR/AUNf94lis1ztoL9t0QyYnzYdUgbrAJXB1FL4OEJMXZmD5jK1MaVRDhlAQ9qVcA9LW6vVIn0Up+4m/v7k16xko9rqvXY9LQ4Hkw+KmdD7T/H+bB5iHWbHHpZ7tjCQkotdjQw5xWQZwLvBK3AVNJ9bSaWDIKINVrQrNLcRehbfBGuV3ULid7ipRyfCWxfClnbG4KLP/wT3etan5O52rL3nqGXLH/sQ/sXqk0yDUQkBm21+3hdrSzenwv2iK7pMCw9zdSv4xSFk+rgo+TQHjy7H5XhLHCHAGY3J0jpLqVrSVzsI1LB6M5fl2EoMEAoEitEttFUo1DRkUtPGGILT1M/+SZ5kTvlqBdC12PmY1XpDGBtyepPcth3j49FmjI4RPaswm+SaQz3uIxC+B8RFLM9GrhWgunW0sQcc4r6JCcQLDyC3KKkd8pKKh40b6o9WQLwaJrrrRv6Taq606c86H8sKGxRQ1iq1uTKn14K5aCX7hZ/kcu8bS/Q9WuXB2GDXcjpghm9klVFOw7EoYzV7IDBIIRt06MkLIT0C/MJB/s4Mwp5bsDIejUQnwyr+vVSWirD9Pj2utRGoWuffGIPArjDreTCT43R5j+o8w6TCWWXsRVsESWC1xDaYnMBSzKz6zFbyZbyxPMQMv7YZ9mxtLKX2Qfn6shCR4jKc9NiC09TP/kmebUlT624AE8Iika5+mDohXq9f2PXvHogeO3Gk9aWzC1qLUoO9GoKg0H9dBeIcrk/mTRsPLLZD1+nXPFdWSFivvspMwhgZYIHBiJsCOKU4KoWHPYSVpCMwsRMRV0YmXEHAJzxpxtwqoC5Z/uCi7ME8loQwLLSzeFEuVfe4edP+YyrEsp6nSACJCbS0IStsh/iG7uvNvEfRkJupBy3Z8hSEMHL9kaL85lzU9YPUST3gTYnG+8gClZWFN+gZW1jJ4sctGEQkRLFIksxr5XHrcXp6A2ig+YdKzGIJBDAstLN4US59PE4fRZTRwzCQai4/k8/KzMiF6rmy9MtuwLLNTE9qpxe4A0CKxovexc5zP3i6H/JoN1vL7Glq2WWGxCZlzBz7QdkOb+HNdSvhifwB9WCMCEiv77tnOreTtSRNk0mhACHpnCjYx5XGEgFCE1XRfN+HcSb3TrblWRc/PUaIZNxYlpEMFa/sWUj2dwTidneZ5Wedvp3EOKiSx7uHGOjLfVqUWaUEcqinpriak1JwUr1GLDcE4nZ3meVnnb6dxDiokse7hxjoy31alFmlBHKop6a4mpNScFK9Riw3BOJ2d5nlZ52+ncQ4qJLHpUUXOkCncV7Eo1QEv4tzQmgHlR040VVI7z4NIdYdPd+M+zaDlqd/FqgSok0sfKpGvIIEPugth8Yd+zxgsXVHfmErIrx0m04zTX7762vrAXbmNmnMh0e+pkABbfrK80tAMsTwVrOG9pxX8dD52djCFHmx2vNwg2Qeu08E8jaM4uHcHKwry1MnprV44R2lX0o1NWQ196H6RMhw2i92lU5PQijBb4AtFlsQ4L5kL+6EqUeDa8ccY5livsgr67hbSeZOLPEQLPbtCHVmcjwGxOynceWdXadxioHuiT3FepDMlOVStY7ViFvdtA=

Encoding code examples

🚧

The purpose of these example is to demonstrate how to encode submission data. They are not intended to be complete submissions and are intentionally missing required parameters and other necessary elements. Refer to the Submission Fundamentals guide for more information about performing a submission.

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 () {…}
  })