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.

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 fraud detection and prevention.

iovation fraud detection and prevention

To prevent and detect fraud in the webbrowser iovation's has developed 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.

Integration summary

There a two components to iovation's fraud prevention and detection integration:

• JavaScript: You will host ioation's loader JavaScript which will load additional resources used to generate a device fingerprint blackbox string.

• Server: An optional server side proxy that you implement to send first party requests for iovation resources from your domain to iovation. This makes it appear as if iovation's assets are coming from your domain so they are not rejected by script blockers.

  ⚠

  We don't require the server side intergation, but you may implement it if you want. Refer to the server integration section below to learn more.

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:

Step-by-step overview

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.

Acquiring iovation's JavaScript

You will need to host iovation's JavaScript loader file. You can get the file in one of the following ways:

• If you are currently assigned an Implementation team, then you can contact your Implementation Engineer.
• If you already have an account at our Support Community, then you can access the loader file directly at the following URL: https://support.bazaarvoice.com/s/article/iovation-web
• If neither the above apply, then you should contact our Support team

Continue reading to learn about the different JavaScript integration options provided by ioviation and how to use them in conjunction with the Bazaarvoice Conversations API.

JavaScript integrations

Use one of the following integration methods to add iovation to your website:

• Hidden form field
• Callback function
• getBlackBox()

Once you're able to generate a device fingerprint black box string, you can then submit it to Bazaarvoice along with the author's content.

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's 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 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.

Encoding code examples

These examples demonstrate how to encode submission data. Refer to the Submission Fundamentals guide for more information about performing a submission.

• Plain JavaScript
• jQuery

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

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

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

Appendix

Troubleshooting

If things do not appear to be working, you can use the loader configuration trace_handler paremeter to troubleshoot. This will provide output and status messages to your callback function.

window.IGLOO.trace_handler = function(message) {
  console.log(message)
}

Server integration

iovation can use resources requested from both your domain (1st party) and iovation's domain (3rd party). Including scripts from both of these domains allows iovation to:

• 1st party - Collect device information for users whose browsers are configured to disable 3rd party JavaScript, or that block the iovation domain.
• 3rd party - Share fraud history for devices and accounts across iovation subscribers.

Loading the 1st party resources will require you to set up reverse proxy as described below.

Configuring 1st party resource retrieval

You will host iovation's JavaScript loader, which creates script tags requesting both their 3rd party and 1st party JavaScript. The 1st party resources will be requested from your domain with a path of /iojs/. For example:

You will need to set up a reverse proxy that forwards any request with the path /iojs/ to iovation. Your proxy should use the following configuration values:

The /iojs/ path segment is included so that you can identify which requests to proxy. It should not be included in the proxied request path. This is demontrated in the table below:

Proxy guidelines

Your proxy to iovation must meet the following guidelines:

• Don't forward requests to the URL directly to iovation through a redirect, because those requests can be blocked.
• Don't create a special sub-domain. This can be just as easily blocked as iovation's domain.
• Don't cache the results from iovation. The resources loaded by iovation are dynamic in nature and may change with each device.
• Don't forward the request to iovation in way that drops the headers.

Doing any of the above will break the fraud recognition process.

Proxy examples

The following simplified examples demonstrate how to configure a reverse proxy using several popular servers:

• NGINX
• Apache
• Node

        server {
          ... other configuration entries ...
          location /iojs/ {
            proxy_pass https://first.iovation.com/;
          }
          ...
        }
      

        LoadModule proxy_module modules/mod_proxy.so
        LoadModule proxy_http_module modules/mod_proxy_http.so
      

        SSLProxyEngine  On
        ProxyPass /iojs/ https://first.iovation.com/
      

        const http = require('http');
        const httpProxy = require('http-proxy');

        const proxy = httpProxy.createProxyServer({
          target: 'https://first.iovation.com/'
        });

        const server = http.createServer(function(req, res) {
          // Match '/iojs/'
          const pattern = /\/iojs\//g;
          // Proxy any request that includes '/iojs/'
          if (req.url.search(pattern) !== -1) {
            // Remove '/iojs/' from request path
            req.url = req.url.replace(pattern, '/');
            proxy.web(req, res, {});
          }
          else {
            // Handle your resources
          }
        });
      

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