# TMA / Iovation front-end integration

## 1. Configure the first-party script proxy

To deliver the first-party dynamic JavaScript components:
* You must tunnel requests through your site to iovation's servers.
* To do this, set up a reverse proxy that will forward all requests sent to a specific URI on your site to iovation's servers. You can define this URI in the configuration variables for the iovation-provided script.

**Important:** Do not cache the dynamic script using a CDN.

### Example configuration using NGINX

server {
  # Other configuration entries

  location /iojs/ {
    proxy_pass https://first.iovation.com/;
  }
}

### Example configuration using a Cloudflare worker

# Get the execution environment
const APP_ENV = 'stg';

addEventListener('fetch', event => {
  const url = new URL(event.request.url);

  // Proxy the Iovation first-party script
  if (url.pathname.startsWith('/iojs')) {
    const iovationOrigin = APP_ENV === 'prd' ? 'https://first.iovation.com' : 'https://ci-first.iovation.com';
    const iovationUri = url.href.replace(`${url.origin}/iojs`, iovationOrigin);
    event.respondWith(fetch(iovationUri, event.request));
    return;
  }

  // Proxy the original request
  event.respondWith(fetch(event.request.url, event.request));
});

## 2. Configure the device recognition/collection script

To configure the Iovation script, you must define settings for a configuration object that is used by the script. 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 || {
  enable_flash: false,
  loader: {
    version: 'general5',
    subkey: 'PmDbidjGyHdWLOlel541XENqtTCYSLt0tZxs-EE-LQo',
  },
};

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

## 3. Collect the blackbox to be used in various API calls
The Iovation script creates a blackbox that you must collect and send to our API. This blackbox will contain all the device information collected from the various sources.

Even though there are three ways to collect the blackbox, we suggest using the `getBlackbox` function. This function returns an object that contains the current value of the blackbox along with a flag indicating whether the collection process has completed.

const {
  blackbox, // the updated value of the blackbox
  finished, // whether all the collection methods have completed
} = window.IGLOO.getBlackbox();

## 4. Send the blackbox value to the required APIs
The Iovation blackbox value is validated server side for fraud detection. For that to work as expected, the following TMA APIs accept an `iovationBlackbox` input which is the value retrieved in the previous step:

* `authorizeProvider`
* `createPayment`
* `createUser`
* `login`
* `resetPassword`
* `verifyWithAuth`