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: 

session_id=16a9508e007c82f33572ac0907f1ec1b
CODE

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.

 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. 

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. For these features, please use Advanced Profiling Integration.

Profiling Tag Code Sample

Tag Parameters

There are various parameters that are specified in the profiling tag:

  • org_id (mandatory): a string of characters that serves to uniquely identify a ThreatMetrix customer. See the Org ID article for more information.

  • session_id (mandatory): a unique identifier that identifies this one event performed by the user. See the Session ID article for more information.

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

  • Custom Profiling Domain (optional): this is the domain that serves the JavaScript tag. The default is h.online-metrix.net. Customers can optionally implement the Enhanced Profiling feature whereby ThreatMetrix hosts an SSL certificate on behalf of the customer. The result is that the profiling domain then points to a hostname that appears to be hosted by the customer, and not ThreatMetrix. This has several benefits. See the Enhanced Profiling 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 which 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.

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

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

Session ID

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

Enhanced Profiling via Hosted SSL

It is recommended that all ThreatMetrix customers use the Enhanced Profiling feature. This increases the accuracy of device profiling and reduces the visitor’s potential concern about third-party content on your website. With the enhanced profiling service, all profiling requests from the visitor’s browser or native mobile app will be made to a domain that is secured by the customer's SSL digital certificates.

In order to profile a device, ThreatMetrix profiling tags are placed on your website, or the ThreatMetrix SDK is embedded in your native app. The tags/SDK will request objects from, and transmit data to the ThreatMetrix profiling server. Because the ThreatMetrix profiling server is a different domain than the original domain from which the initial page or app typically requests resources, visitors who are monitoring the network requests can see that the requests are being made to a third-party server.

Enhanced Profiling also prevents the blocking of third party requests, either natively as a feature of the browser, or using third party browser privacy tools.

The deployment timeframe for SSL Certificates is 5 to 7 days upon receipt of the SSL Cert, bundle certs and root CA. All of these file are required to minimize the deployment time of the SSL Certs.

Please note that Enhanced profiling is not intended to change the third party cookie to a first party cookie, and is purely to ensure that all requests appear to come from the customer domain.

Select a sub-domain name for your profiling server

Choose a hostname that will not indicate that the server is used as a security measure. This must be a sub-domain; it cannot be a top domain.

For example:

  1. content.yourdomain.com

  2. img2.yourdomain.com

  3. cdnA.yourdomain.com

Once you have determined the hostname used for profiling, you’ll need to provide it to your ThreatMetrix services representative, along with the following information:

Mandatory:

  1. Organization Name:  Name of the company (e.g., Lemon Bank, Inc.)

  2. Common Name or Fully Qualified Domain Name: Sub-domain that has been chosen (e.g., http://content.lemonbank.com ) 

  3. Country Name: 2 letter code (e.g., US)

  4. State or Province Name: Full name of the state or province (e.g., California)

  5. Locality Name: Full name of the locality, such as the city (e.g., San Jose)

Optional:

  1. Organizational Unit Name:  Section name (e.g., Services) 

 The information outlined above is the minimum information needed to create a CSR. Your Certificate Authority (CA) may require additional information. Please check with them prior to providing this information to ThreatMetrix to ensure that the CSR is created per the CA requirements.

For the purposes of illustration, the following examples use content.yourdomain.com. If you decide on a different name, then simply substitute it in the instructions outlined.

Obtain the CSR for your profiling server hostname and a signed certificate file

ThreatMetrix generates a certificate signing request (CSR). ThreatMetrix delivers the CSR to you to be signed by your preferred trusted Certificate Authority (CA). Please rename the signed cert, intermediate cert(s) and root certificate to .txt format and return to ThreatMetrix. The certificate should be in PEM format. We will only support a certificate with an expiration of at least 1 year.

In addition to supplying the CSR, ThreatMetrix will also supply to you the dedicated hostname that will be assigned for your profiling server. This unique hostname will be required for you to configure your DNS. Once your SSL certificate is deployed, ThreatMetrix Support or Services teams will inform you of how the CNAME DNS record should be created.

 Please note that If your corporate security policy does not allow ThreatMetrix to generate the CSR, contact your ThreatMetrix services representative to discuss alternative methods

 In the event that a wildcard certificate is deployed a FQDN is required for monitoring proposes. This will require you to create an entry as outlined in the example above and provide this to ThreatMetrix.

Update profiling code to use the new hostname or configuring the Mobile SDK

After you have received confirmation from ThreatMetrix that your SSL certificate is deployed to the profiling servers, you should change the hostname used in the profiling tags and/or SDK to content.yourdomain.com.

 For the Mobile SDK, the following parameters need to be configured with the sub-domain once the certificate is active:

  1. Android – setFPServer

  2. iOS – THMFingerprintServer

You should only make this change after you have verified that the certificate is deployed. Making this change prior to the certificate deployment (even if the DNS changes are complete) may generate security warnings in your end-users web browsers.

Advanced Profiling Integration

This section outlines how to use the Profiling Javascript Toolkit to implement profiling rather than using the Basic Profiling Integration (tags.js script).

 The benefits of using this profiling integration are:

  • Better defense against adblockers with URL encryption.

  • Customer ability to re-profile by calling the profile() function multiple times.

  • Reduction of unknown sessions due to adblocked profiling domain.

Installing the snippet and invoking profiling

 Please note that this toolkit is updated from time to time and we recommend that customers  download the latest version.

Latest Release: fp-clientlib-v4.js (Version 4)

Release Date: May 18, 2021

Download the latest version:  fp-clientlib-v4.js

  1. Download the toolkit. Please note that the location of the file has changed from cloudfront which will no longer be updated. Customers should migrate to the new version of the library and are advised to host this JS file on their own websites.

  2. Rename the downloaded file to something unique. E.g. asdfghjkl.js

  3. Place the renamed file in a publicly accessible location on your web server. You may rename this file to any description you see fit. 

  4. Include a reference to the toolkit on the page you wish to have profiled:

    <script type="text/javascript" src="path/to/toolkit.js"></script>
    CODE

  5. Trigger profiling asynchronously by calling it in a script on your page and including appropriate parameters: 

Please ensure that the function 'threatmetrix.profile' is renamed; this function is part of the toolkit customers download when implementing tag obfuscation and should be renamed or randomized so that it does not call attention to the fact that ThreatMetrix is being used.

<script type="text/javascript">threatmetrix.profile(profiling_domain, org_id, session_id, page_id);</script>
CODE

Substitute profiling_domain, org_id, session_id, and optionally page_id with appropriate parameters.

Note that you will need to generate session_id on your server-side in order to reference the session-query from your back end.

Profiling domain will be "h.online-metrix.net" if you have not setup Enhanced Profiling via self-hosted SSL.

For example:
<script type="text/javascript">threatmetrix.profile("h.online-metrix.net", "abcd1234", "01f50c4d1430a620a3b50005ffe98541");</script>
CODE
Example (JSP)

An example of how the client toolkit could be used on a single-page JSP application would involve:

<head>
<script type="text/javascript" src="path/to/toolkit.js"/>
<!-- other head content -->
<head>
<body>
<script type="text/javascript">
    var session_id = <%=generateSessionId()%>;
    threatmetrix.profile("<profiling_domain>", "<org_id>", session_id);
</script>
<noscript>
         <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="<profiling doman>/fp/tags?org_id=<org_id>&session_id=<session_id>"></iframe>
</noscript>
</body>
CODE

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. 

Using the Completion Notifier

Customers can implement the Javascript completion notifier as described in Profiling Notification Completion.

 

Receiving this notification implies tags.js was delivered and was run.

Quick Check

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

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

 

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

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 page load to give a function a boolean result.

 

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