Device Risk with REST API

To use Device Risk as a standalone service you can:

Integrate a JavaScript from Iovation to capture the blackbox data from the end user's device.
Upload the blackbox string as a Prepared Data credential using the Jumio REST API.
Call the finalize API to process the transaction.

Integrating the Iovation JavaScript

Download the loader.js JavaScript file from Iovation for generating the blackbox.

Multi-Domain Recognition

The Iovation script will dynamically load additional resources from both your domain (the First-party domain) and TransUnion's domain (the Third-party domain). Including scripts from both of these domains allows the following:

Third-Party JavaScript: Share fraud history for devices and accounts across TransUnion subscribers.
First-Party JavaScript: Collect device information for users whose browsers are configured to disable third-party JavaScript, or that block the TransUnion domain.

This script will load the appropriate resources from both sets of domains. Components loaded by the script are dynamically generated and therefore not included with the script provided, nor should they be directly included on your page.

Retrieving the dynamic first party script will require you to implement a reverse proxy in your own domain to redirect the script requests through your own servers. This avoids potential problems with browsers canceling the requests.

Configuring the JavaScript

To configure the Iovation JavaScript you must define settings for a configuration object that is used by the JavaScript. If the object is not defined, default values will be used.

The configuration object has various sections and looks something like the following:

/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  "bbout_element_id" : "iobb",
  "bb_callback": null,
  "loader" : {
    "uri_hook" : "iojs",
    "version" : "general5",
    "subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
  }
};

You will receive a configuration script in addition to the collection script. You can include these separately, combine them or in-line the definition on your page.

It is critical that the configuration comes before TransUnion's loader script otherwise configuration variables will not be used once the script starts running.

Configuration script sections

TransUnion Global Object Name

Before delving into the options available, a quick word on the io_global_object_name, IGLOO, by default. In earlier versions of the scripts, TransUnion configured the script through the use of global variables. While this approach is simple enough, it can add a lot of additional variables to the window object which has the potential to collide with other scripts.

To remedy this, TransUnion has created an object that encapsulates all of the settings and functionality and you can change the ID to prevent potential collisions by changing the name.

window.io_global_object_name = "<your custom name>"

If you do change the value, references functions and values as follows:

window.<your custom name>.xxxxx

Change the following as well:

window.IGLOO = window.IGLOO ||

to match your new custom name.

TransUnion configuration object has 2 main components:

Generic settings that indicate how to retrieve a device print and restrictions on what information is collected, for instance Flash values
Loader settings that indicate how to access first-party components and basic debug and versioning information

Each set of configuration options belongs in a specific section of the object:

/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  // generic settings go here as
  // "option" : value
  ...
  "loader" : {
     // loader configuration options go here as
     // "option" : value
  }
};

Generic Configuration Options

Parameter Type Default Value Description

bbout_element_id string, optional The ID of the HTML element to populate with the blackbox from the third-party JavaScript. If bb_callback is specified, this parameter has no effect.

bb_callback

function, optional

Parameter	Type	Default Value	Description
bbout_element_id	string, optional		The ID of the HTML element to populate with the blackbox from the third-party JavaScript. If `bb_callback` is specified, this parameter has no effect.
bb_callback	function, optional		This JavaScript function is an event handler that is called when a collection method has finished updating a blackbox. This must be a function, not a string Declare the function as follows: "bb_callback" : function ( bb, complete) { // code to process blackbox here } The variables store the following: bb – the updated value of the blackbox complete – a boolean value indicating whether all the collection methods have completed.
enable_rip	boolean, optional	true

This JavaScript function is an event handler that is called when a collection method has finished updating a blackbox. This must be a function, not a string

Declare the function as follows:

"bb_callback" : function ( bb, complete) {

   // code to process blackbox here

}

The variables store the following:

bb – the updated value of the blackbox
complete – a boolean value indicating whether all the collection methods have completed.

enable_rip boolean, optional true

Loader Configuration Options

Parameter	Type	Default Value	Description
uri_hook	string, optional	iojs	Location of dynamic first party components. This should be a reference to the web directory being proxied. You can use relative or absolute references, but should not use a complete URL. For example, if your reverse proxy is accessed from http://mysite.com/iov/wdp/...., and your page is loaded from: http://mysite.com/app/mypage.html, you would use: "uri_hook" : "/iov/wdp" If the reverse proxy is accessed at http://mysite.com/app/iojs and your page is at http://mysite.com/app/page.html, you might use: "uri_hook" : "iojs" This should not be a URL (i.e. include http(s)://host:port) as this will fail and the scripts must be loaded from the same domain as the page.
subkey	string, optional		This will be an TransUnion assigned value that tracks requests from your site. This is primarily used for debugging and troubleshooting purposes.
version	string, required	general5	This is the version of the script to load. The value should either correspond to a specific version you wish to use, or one of the following aliases to get the latest version of the code: general5 - the latest stable version of the JavaScript early5 - the latest available version of the JavaScript general5 and early5 may be the same code, however, any new changes will be released on early5 prior to general5. Once the new release has been vetted in production and deemed satisfactory, general5 will be updated to match early5.
trace_handler	function, optional		This JavaScript function can be used to provide tracing messages for the script. This will provide information on the progress of the script and is useful for debugging purposes. Declare the function as follows: "trace_handler" : function (message) { // process/record trace message here } where message is the trace message provided by the script.

Example Configuration File

/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  "bbout_element_id" : "iobb",
  "loader" : {
    "uri_hook" : "/iojs",
    "version" : "general5",
    "subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
  }
};

Define the bb_callback Function

The callback interface allows you to manage blackbox generation in a more event-driven manner. As blackbox collection progresses,the script fires update events as collection methods complete. These events trigger a user-defined callback function to update the page with the new blackbox value. When all of the collection methods are completed, a Boolean flag is set indicating no further updates are expected and the value is the final blackbox value.

In the JavaScript configuration parameters, set the bb_callback parameter to a function that processes the blackbox value, and that has the following signature:

function bb_update_callback( bb, complete)

Where:

bb is the updated value of the blackbox
complete is a boolean value that indicates whether all collection methods (Flash, etc.) are complete

/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  "bb_callback": function ( bb, complete ) {
                      var bb_field = document.getElementById( "bb" );
                      bb_field.value = bb;
                  },
  "loader" : {
    "version" : "general5",
    "subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
  }
};

If bb_callback and bbout_element_id are both specified, the hidden field specified in bbout_element_id will not be populated, unless explicitly done so by the function specified in bb_callback.

To Configure the Reverse Proxy:

Set up a proxy configuration within your domain.
Specify a URI for iojs on your site. Using the URI, forward any requests beginning with: http://my.domain.com/iojs
Direct the proxy to forward the requests to the following URL:

https://first.iovation.com

Example NGINX Configuration

Edit the default.conf configuration file and add the following lines to the server section:

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

Uploading the Blackbox as Prepared Data

A request to update or create an account that references a workflow that calls Device Risk will include a DATA credential with a "device_risk" part. The JSON object for the credential will include the bearer token and URL for uploading the blackbox obtained from the Iovation SDK.

    "credentials": [
      {
        "id": "9d79ed28-947b-4b83-9dfc-80b64467d70c",
        "category": "DATA",
        "label": "DATA",
        "allowedChannels": [
          "API"
        ],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLiycemQ1S07MCfpBugQIIRYu8EdkD3dHXeK_Tn4R72IVWuudREuBQOuyBmJ5_dY3LWVqEYEmSfS6s4dGRjSUqRypf_MI0xWSNAFZs4G6gLg3R1cmyiC078GP0fbuc-pl6343W9yWX7pt-_GblFHpBT6ZCxDWAaCj0NKdFVEWN4fwAX03Be4wAAAA.wR-1U9aOdOk4gJiDc665u2i4-clB8-g2CATM1YODcFuDec5_gumFa2wJh7eoMPGoZoJmWXEEMDZaG6VjSLajZw",
          "parts": {
            "device_risk": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32/credentials/9d79ed28-947b-4b83-9dfc-80b64467d70c/parts/DEVICE_RISK"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32"
        }
      }
    ]

Prepared Data

Key	Type	Mandatory	Description
sessionId	string	Yes	Blackbox obtained from Iovation SDK.

Example: Prepared Data Body

{
    "sessionId": "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"
}