iovation Integration (Device Data Aggregation) – Alloy

TABLE OF CONTENTS

How to pass Blackbox string
iOS SDK
Android SDK
Web SDK - Third Party and First Party
- HOW TO IMPLEMENT THIRD-PARTY SCRIPT
- HOW TO IMPLEMENT FIRST-PARTY SCRIPT
- RESOURCES

How to pass Blackbox string

The collected iovation black box string is attached to a request body to the /evaluations endpoint in the following way:

iOS SDK

An iOS SDK for iovation Blackbox collection can be found here: https://github.com/iovation/deviceprint-SDK-iOS

Android SDK

An Android SDK can be found here: https://github.com/iovation/deviceprint-SDK-Android

Web SDK - Third Party and First Party

❗️ This implementation guide assumes you have an HTML website that sources code within index.html and index.js and iovation.js and config.js for client-side and server.js for server-side.

HOW TO IMPLEMENT THIRD-PARTY SCRIPT

1. Add the snare.js file via an HTML <script> tag.

Instructions from the iovation BB PDF

<script type="text/javascript" src="<https://ci-mpsnare.iovation.com/snare.js>"></script>

Example code snippet on adding snare.js via the Test URL

2. Load the index.js file after snare.js. This file will call on functions defined from snare.js so it should be loaded after any other iovation scripts have loaded.

3. iovation has several global variables that are optional to include. If they are included, they do need to go at the top of the index.js file. They are used globally by iovation to determine how the iovation script collects data and interacts with the end-users. See the PDF for more details on what variables can (optionally) be included.

var io_install_flash = false; 
var io_install_stm = false; 
var io_exclude_stm = 12; 
var io_enable_rip = true;

Example code from iovation BB PDF setting the variables in an HTML file

4. Call the method ioGetBlackbox when the application form is submitted by adding a function that calls this method to index.js.

function send_bb() {
// make AJAX call here or do something else with blackbox
// for illustration purposes, we are just going to do an alert here
  var bb3 = ioGetBlackbox();
  alert( "Third party bb: " + bb3.blackbox );
}

Example code from iovation BB PDF setting the variables in an HTML file

5. When ioGetBlackbox is called, it will return is the blackbox key.

❗️ You may notice that ioGetBlackbox() is not specifically defined by code we added. Instead it is defined by the script tag for snare.js that was previously added via the HTML. This function returns an object that contains the current value of the blackbox along with a flag indicating whether the collection process has completed.

Why add both the first-party and third-party scripts?

Source: iovation FraudForce Integration Guide for REST PDF

As browser security features are released, third-party scripts and tracking can be blocked. The goal is to get iovation to run but without the browser window knowing iovation is doing the work. The requirement for that is to set up a server-side reverse proxy where essentially the script is loaded and the browser thinks it's part of the website and would not be blocked by browser features or services that block the iovation domain.

HOW TO IMPLEMENT FIRST-PARTY SCRIPT

❗️ Setting up the first-party script requires having engineering resources with an understanding of how to setup a reverse proxy.

1. Setup a proxy configuration within your domain.

2. Specify a URI on your site to proxy the request. The default URI is iojs , however you can change this in the configuration section of your iovation Javascript. Using the default URI, forward iovation any request beginning with: http://your.domain.com/iojs. Add this to your index.html file above snare.js .

<script type="text/javascript" src="<http://localhost:4242/iojs/>" defer="defer"></script>

Example code snippet on hosting iojs on localhost:4242 domain

3. Direct the proxy to forward the requests to iovation at the following URL in your server.js file.

Test and Production Server URLs from iovation FraudForce Integration Guide for REST PDF

Any reference to iojs, no matter what it is, you want to pass all those references to ci-first.iovation.com/* (or first.iovation.com/* when connecting to iovation Production).

4. Create two additional JS files and add them to index.html above the iojs file:

config.js - To configure the iovation JavaScript, you must define settings for a configuration object that is used by the JavaScript. The example app uses the default values provided by the iovation FraudForce Integration Guide for REST PDF.
iovation.js - Contains the loader JS script

5. In the config.js file, add the sample code of the default setup. If the customer wants to use a different endpoint on the server, it must match in the uri_hook property in config.js.

/* Copyright(c) 2018, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO"
window.IGLOO = window.IGLOO || {
  "enable_flash" : false,
  "bbout_element_id" : "ioBlackBox", // this can be changed to store in a different hidden field (or removed to use a different collection method)
  "loader" : {
  "subkey" : "",
  "version" : "general5"
} };

Sample code of the default setup. Configuration from iovation FraudForce Integration Guide for REST PDF file. Additional options and values that can be obtained from the file

6. In the iovation.js file, add the iovation Loader Javascript library (see iovation loader.js in the Resources section).

7. In index.js, add in the JavaScript function window.IGLOO.getBlackbox() to obtain the blackbox via first party where you added the third party function. You may want to consider adding a check to fallback to the first-party script if the third-party script was not loaded, like in the following example.

const iovationHandler = () => {
// ioGetBlackbox() is loaded by the 3rd-party snare.js script which is included in index.html
const thirdPartyBlackbox = typeof(ioGetBlackbox) === 'function' ? ioGetBlackbox().blackbox : null;

// getBlackbox() is magical function that is loaded using iovation.js (loader.js), which calls the URI specified in config.js that points to the backend proxy
const firstPartyBlackbox = window.IGLOO.getBlackbox().blackbox;

// for illustration purposes, we are just going to do an alert here
console.log('3rd party Iovation Blackbox', thirdPartyBlackbox);
console.log('1st party Iovation Blackbox',firstPartyBlackbox);

reqBody.iovation_blackbox = thirdPartyBlackbox || firstPartyBlackbox;
};

This sample code is meant to only illustrate one possible way on how you can set up the code

RESOURCES

Integrating with Web Sites PDF

See attachment iovation Integrating with Web Sites.pdf

iovation loader.js

/*
Copyright(c) 2018, iovation, inc. All rights reserved.
*/
(function B(){function v(e,a){var b={},c;for(c=e.length-1;-1<c;c--)0<c?b[c]=function(){var d=c;return function(){return w(e[d],b[d+1],a)}}():w(e[c],b[c+1],a)}function w(e,n,k){var c=document.createElement("script"),f,g,l;l=A(a[k]&&a[k].staticVer&&a[k].staticVer+"/"||e[1]);e[0]=e[0].replace("##version##",l);f=e[0].split("?")[0].split("/");g=f[f.length-1].split(".")[0];u.test(e[1])&&l!==e[1]&&d("loader: Overriding configured version with staticVer.");c.setAttribute("src",e[0]);c&&c.addEventListener?
c.addEventListener("error",function(){b[k+"_"+g+"_load_failure"]="true"}):c.attachEvent&&c.attachEvent("onerror",function(){b[k+"_"+g+"_load_failure"]="true"});n&&(c.onload=n);document.getElementsByTagName("head")[0].appendChild(c)}function d(e){if("function"===typeof a.trace_handler)try{a.trace_handler(e)}catch(b){}}function f(b,a){var d=null!==b&&void 0!==b;return!d||"1"!==b.toString()&&"true"!==b.toString().toLowerCase()?!d||"0"!==b.toString()&&"false"!==b.toString().toLowerCase()?"boolean"===
typeof a?a:!1:!1:!0}function A(a){d("********** version before replace: "+a+" **********");d('localNamespace[ "url_dots_to_dashes" ]: '+b.url_dots_to_dashes);d("numericVersionPattern.test( output ): "+u.test(a));b.url_dots_to_dashes&&u.test(a)&&(a=a.replace(/\./g,"-"));d("version after replace: "+a);return a}var g=window,x=g.io_global_object_name||"IGLOO",a=g[x]=g[x]||{},b=a.loader=a.loader||{},y=[],z=[],u=/^[0-9]{1,3}(\.[0-9]{1,3}){2}\/$/;if(b.loaderMain)return d("loader: Loader script has already run, try reducing the number of places it's being included."),
!1;b.loaderMain=B;b.loaderVer="5.2.2";(function(){var e=f(b.tp,!0),n=f(b.fp_static,!0),k=f(b.fp_dyn,!0),c=f(b.enable_legacy_compatibility),u=f(b.tp_split),v=b.tp_host&&b.tp_host.replace(/\/+$/,"")||"https://mpsnare.iesnare.com",l=b.fp_static_override_uri,m=void 0!==b.uri_hook?b.uri_hook+"/":"/iojs/",p=(b.version||"versionOrAliasIsRequired")+"/",w=b.subkey?g.encodeURIComponent(b.subkey)+"/":"",x=b.tp_resource||"wdp.js",q=b.tp_host?"&tp_host="+g.encodeURIComponent(b.tp_host):"",C=l?"&fp_static_uri="+
g.encodeURIComponent(l):"",r,t,h;b.tp_host=v;r=f(a.enable_flash,!0);t=a.io&&a.io.enable_flash;h=a.fp&&a.fp.enable_flash;t=void 0!==t&&null!==t?f(t,!0):r;void 0!==h&&null!==h?h=f(h,!0):t=r;r=t?"&flash=true":"&flash=false";h=h?"&flash=true":"&flash=false";q="?loaderVer="+b.loaderVer+"&compat="+c+"&tp="+e+"&tp_split="+u+q+"&fp_static="+n+"&fp_dyn="+k+C;e||n||d("loader: Not currently configured to load fp_static or tp script(s).");a.fp&&a.fp.staticVer&&a.fp.staticVer+"/"!==p&&(p=A(a.fp.staticVer+"/"),
d("loader: Configured version replaced with that from pre-loaded static script."));n||a.fp&&a.fp.staticMain?(m=(m+"##version##"+w).replace(/\/\//g,"/"),n&&(a.fp&&a.fp.staticMain?c&&!a.fp.preCompatMain&&d("loader: enable_legacy_compatibility on, but included static does not have the compat wrapper."):l?y.push([l,""]):y.push([m+"static_wdp.js"+q+h,p])),!k||a.fp&&a.fp.dynMain?a.fp&&a.fp.dynMain&&d("loader: First party dynamic script has already been loaded, disable fp_dyn or make sure you're not manually including the dynamic file separately."):
y.push([m+"dyn_wdp.js"+q+h,p])):f(b.fp_dyn)&&d("loader: Invalid Config, first party dynamic script set to load without static.");e&&(a.io&&a.io.staticMain?d("loader: Third party script has already been loaded."):(m=v+"/##version##"+w,u?(z.push([m+"static_wdp.js"+q+r,p]),z.push([m+"dyn_wdp.js"+q+r,p]),b.tp_resource&&d("loader: Invalid Config: both tp_resource and tp_split set. Ignoring tp_resource.")):z.push([m+x+q+r,p])))})();v(y,"fp");v(z,"io")})();

Integrating with Web Sites.pdf
100 KB Download