Skip to main content
Skip table of contents

Implementation: LexisNexis ThreatMetrix Web - Canada

Introduction to Profiling

Profiling is the process of placing tags within a web application specific to data processing. You will need to identify the pages in your web application that provide the optimal opportunity for profiling. Typically, profiling takes between 2 and 5 seconds to complete, so when selecting the page/s, typically, those containing forms that require the maximum data input will ensure that the visitor stays on the page for the time necessary to complete profiling.

Please note that the majority of profiling is completed within a fraction of a second but may take up to 5 seconds to collect the full set of profiling attributes.

Common pages for tag placement

  • Account creation page: a page in which a visitor registers as a new user of a website.

  • Payments page: a page in which a payment, transaction, or checkout is processed.

  • Login page: a page in which a visitor logs into a website. (Future Use case)

Session ID

The Session ID is a temporary identifier that is unique to the visitor's session. It is the primary element used to identify and query end-user sessions on customer websites. Both ThreatMetrix Cloud and ThreatMetrix Mobile require a Session ID to be present during a session as detailed below:

ThreatMetrix Web

The Session ID must be a unique ThreatMetrix Session ID to be included within the Profiling Tags in order for our service to uniquely identify the end user's session. The Session ID must be generated by the customer's web application.

Generating a Session ID

Some recommended methods of generating a Session ID are:

  • Referencing an existing session identifier from a cookie and appending the date and time in milliseconds to the end of the identifier and then applying a hexadecimal hash to the concatenated value to produce a completely unique Session ID.

  • Referencing an existing session identifier from the web application and applying a hexadecimal hash to the value to obfuscate the identifier.

  • Generate a completely arbitrary, random number.

Inserting the Session ID into the Profiling Tags

Once the Session ID has been generated it needs to be inserted into the profiling tags in the session_id= field as in the following example: 

CODE
session_id=16a9508e007c82f33572ac0907f1ec1b

NOTE: A full example of the Profiling Tags can be seen in the Profiling Tags documentation. Note the session_id= parameter.

Session ID Format

The Session ID may be up to 128 bytes long and must consist of the following characters only:

  • Upper and lowercase English letters (a-z, A-Z)

  • Digits (0-9)

  • Underscore (_)

  • Hyphen (-)

Session ID Length

session_ids will need to be at least 10 valid characters long or an empty JS response, 204 (OK) will be returned. Existing organizations may now request to mandate a minimum length of 10 for a session_id.

 The minimum length is after sanitization (removal of non-conformant characters).

If the session_id exceeds 128 characters, it will be truncated to 128 characters in the API response.

Session ID Validation

The validation of the session_id is dependent on whether the Check Session ID flag is set to true or not for your organization. This flag is set to true by default for all new customer organizations. When this flag is set to true, the session_ids will need to be at least 10 valid characters long and no invalid characters must be present. If the session_id does not comply, the profiling call will fail with a 204 (OK) response, and the API response will return the request_result as "fail_invalid_parameter" and the error_detail as "session_id".

 If this flag is not set, then the minimum length will not matter and any non-conformant characters will be sanitized and the call allowed to proceed.

Recommended: An MD5 or SHA hashed value will conform to the above format requirements.

Session ID Notes and Limitations 

  • Ideally, each profiling session should use a unique Session ID. 

  • Multiple API calls may be performed with the same Session ID as long as no new profiling was done, as the calls will access the same session data.

  • handle_id is a deprecated attribute that has been superseded by session_id

Sending a Session ID to Payrix

After you’ve used the steps above to create a ThreatMetrix Session ID, you’ll need to send it to Payrix for risk validation.

Steps to send a ThreatMetrix Session ID using the PayFields payment page and API /transactions endpoint are coming soon.

See the content below for steps to send a ThreatMetrix Session ID:

Creating a Merchant

The first method to send a ThreatMetrix Session ID is to send an API request to create a merchant and include the Session ID in the optional tmxSessionId field. See the example below:

Request:

CODE
POST /merchants

Headers:

CODE
Content-Type:application/json
APIKEY:{{private_api_key}}

Example Request Body:

JSON
{
  "entity": {parent entity ID}
  "New": 0,
  "type" : 1,
  "AnnualCCSales": 1000000,
  "avgTicket": 1250,
  "environment": "ecommerce",
  "status": "Ready"
  "saqDate": "Bakery 1710",
  "name": "Bakery 1710",
  "address1": "123 Happy",
  "address2": "123",
  "city": "West Aisha",
  "state": "TX",
  "zip": "62868",
  "country": "USA",
  "phone": "7027678096",
  "fax": null,
  "email": "Go.Lakers@testmail.com",
  "ein": "775661492",
  "website": "http://testwebsite.com",
  "custom": "example customer id",
  "tcVersion": "411",
  "tcDate": "2020-10-21 10:31:33",
  "tcAttestation": 1,
  "visaDisclosure": 1,
  "disclosureIP": "null",
  "disclosureDate": 20210716,
  "merchantIp": null,
  "currency": "USD",
  "tmxSessionId": "16a9508e007c82f33572ac0907f1ec1b",
  "merchant": {
      "dba": null,
      "new": "1",
      "mcc": "1799",
      "status": "1",
  ]
}

Basic Profiling Integration

This section outlines the basic method for integration profiling into a web page. This method does not support the advanced features of AdBlock defense, re-profiling, or support for single-page applications. 

Profiling Tag Code Sample

Tag Parameters

Various parameters are specified in the profiling tag:

  • org_id (required): a string of characters that serves to uniquely identify a ThreatMetrix customer. Contact your Account Manager to receive your org_id.

  • session_id (required): a unique identifier that identifies this one event performed by the user. See above.

  • page_id (optional): This is used to identify specific pages to the ThreatMetrix Platform to support the Man in the Browser detection functionality. See the MitB documentation for more information.

Supported Tag Deployments

There are various methods available when deploying the profiling tag, detailed below.

Basic <script> Tag with <noscript> (Recommended)

This is the recommended deployment. This includes a basic <script> tag that loads a Javascript resource: tags.js, as well as an additional <noscript> tag. The purpose of the <noscript> tag is to ensure that profiling occurs, even if JavaScript is disabled.

Tag Placement
  • This basic <script> tag should be placed in the <head> tag for optimal performance.

  • The <noscript> tag must be placed in the <body> tag, as in the below example. The <noscript> tag must not be placed in the <head> tag as it contains an <iframe> tag. Placing iframes in the head tag violates W3C validation and may cause issues.

CODE
<head>
    <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=abcd1234&session_id=01f50c4d1430a620a3b50005ffe98541"></script>
</head>
<body>
    <noscript>
        <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top:
-5000px;" src="https://h.online-metrix.net/fp/tags?org_id=abcd1234&session_id=01f50c4d1430a620a3b50005ffe98541"></iframe>
    </noscript>
</body>
Basic <script> Tag

This includes a single <script> tag that loads a JavaScript resource: tags.js. If JavaScript is disabled, this tag will not load and profiling will not occur.

Tag Placement

This basic <script> tag should be placed in the <head> tag for optimal performance.

CODE
<head>
    <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=abcd1234&session_id=01f50c4d1430a620a3b50005ffe98541"></script>
</head>

Session ID

Please read the Session ID article for more information about the Session ID format, length and limitations.

Checking tags.js was run

You may use on of the following different ways to check if tags.js has been delivered and that profiling has started. 

Profiling Notification Completion

This is a per-organization (org_id) feature that may be used for receiving a notification on the completion of Device Profiling. Contact ThreatMetrix® Services to enable this feature.

 

When this feature is enabled, a notification can be made on the completion of Device Profiling. This would include all requests for enabled tag elements (images, JavaScript, and Flash). Certain background JavaScript processes may be included in the delay of the notification, depending on the page design.

Please Note:

Flash has been removed from the profiling service for all customers as of June 24, 2021.

Note: Certain JavaScript processes may continue to look for mouse events, keyboard events, or malware injections, etc., but when this notification fires, Device Profiling will have collected the minimum recommmend profiling data in order to make a session query.

Various profiling features may continue to collect data and may be shown in later session query calls.

  

Implementation

After enablement, a customer can implement one of two methods in javascript to receive this event:

Javascript Direct Function Call

For this method, the customer simply implements a function with the following profile:

CODE
function tmx_profiling_complete(session_id)
  {
    console.log("tmx_profiling_complete called with session_id "+session_id);
}

 

This function will be found if the customer implements it in the frame or window that has a check.js or a tags.js call. It will also be called if the function is defined at the 'top' Javascript level.

While this method is simple to implement, it will not work if the customer has implemented the function across a cross-origin iframe boundary relative to the tags implementation.

Also, customers may be averse to allowing cross-iframe communications. In this case, the customer should use the method below:

Javascript Event Listener

For this method, the customer should register an event listener on the "message" event, with code such as:

CODE
function profiling_complete(event)
{
    //event.data will be in format "tmx_profiling_complete:<session_id>"
    console.log("profiling_complete called with session_id "+event.data.split(':')[1]);
}
if (window.addEventListener)
{
    window.addEventListener("message", profiling_complete, false);
}
else
{
    window.attachEvent('onmessage', profiling_complete);
}

 

Quick Check

A quick way to determine whether the tags.js code was delivered and started may be implemented with the following function:

CODE
function tmx_tags_loaded()
{
    return typeof tmx_profiling_started !== "undefined" && tmx_profiling_started;
}

 

Please note that this will only return true after the profiling process has started. Profiling does not start until shortly after the document OnLoad event, or readyState is complete. In some cases, this may not be true until a second after the page has loaded, so calling this immediately on page load will return false.

This function may be useful when you know the context is at least one second after the page loads.

Callback Method

For a more reliable method of determining whether tags.js was loaded and started, the following JavaScript code may be used. It will trigger a callback one second after the page loads to give a function a boolean result.

CODE
function tmx_tags_started(onStarted)
{
    if (typeof onStarted !== "function")
    {
        return;
    }
    var isWebkit = 'WebkitAppearance' in document.documentElement.style;
    if (document.body && (document.readyState === 'complete' || !isWebkit))
    {
        setTimeout(function(){onStarted(typeof tmx_profiling_started !== "undefined" && tmx_profiling_started);}, 1000);
        return;
    }
    var node;
    if (typeof window !== "undefined" && typeof window !== "unknown" && window !== null)
    {
        node = window;
    }
    else
    {
        node = document.body;
    }
    if (node.addEventListener)
    {
        node.addEventListener("load", function (){setTimeout(function(){onStarted(typeof tmx_profiling_started !== "undefined" && tmx_profiling_started);}, 1000);}, false);
    }
    else
    {
        if (node.attachEvent)
        {
            node.attachEvent("onload", function (){setTimeout(function(){onStarted(typeof tmx_profiling_started !== "undefined" && tmx_profiling_started);}, 1000);});
        }
        else
        {
            var oldonload = node.onload;
            node.onload = new function ()
            {
                var r = true;
                if (oldonload !== null && typeof oldonload === "function")
                {
                    r = oldonload();
                }
                setTimeout(function(){onStarted(typeof tmx_profiling_started !== "undefined" && tmx_profiling_started);}, 1000);
                node.onload = oldonload;
                return r;
            };
        }
    }
}
function myOnTagsJSLoaded(didLoad)
{
    console.log("tmx_profiling_started was "+didLoad);
}
tmx_tags_started(myOnTagsJSLoaded);

 

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.