Please Note:

Web framework v2

This second version of the framework is recommended for all new integrations.

Framework v2 brings several enhancements to the previous version:

Single-page application support
Bug fixes and performance improvements
Smaller scripts

Script integration

Endpoint

<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts Example:

   ...
   <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts"></script>
   ...

To avoid issues on the customer page if the GAH script can’t be loaded, you can add the following lines before including the script:

   ...
   <script> revisitid=ifp_visitId="undefined",ifp_initUseCase=ifp_initView=ifp_finalizeView=ifp_finalizeUseCaseAndView=function(){var i=arguments,e=i.length-1;0<=e&&"function"==typeof i[e]&&i[e]("undefined")};
     </script>
   <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts"></script>
   ...

Request parameters

Parameter	Value	Description	Parameter type	Data type
partners	Optional	Partner script list to include in the current page. By default, all partners scripts are included. The available partners are: `GemaltoRiskEngine` and `ThreatMetrix`. For example: `../script?partners=GemaltoRiskEngine&partners=ThreatMetrix`	Query param	String Default: all partners
auto	Optional	When set to 1 (true), the ifp`_initUseCase` and i`fp_initView` methods are called automatically	Query param	0 or 1 Default: 0
visitId	Optional	Keep a previously generated `visitId`. Useful when the use case is split in several pages.	Quary param	String Default: generate a new `visitId`

Response messages

HTTP status code	Reason	Content
200	Success	Script to execute for collecting data

Ideally, this script should be the first to be loaded. Its size is small and does not impact page loading.

The downloaded script contains all the required methods to later, and also asynchronously loads the partners’ scripts.

ifp_initUseCase

When your customer starts a new use case that needs profiling (such as login), a new visitId is required. To do so, the ifp_initUseCase needs to be called:

   ...
   ifp_initUseCase(callback);
   ...

Method parameters

Parameter	Value	Description	Data type
callback	Optional	A javascript function that is called at the end of the `initUseCase` function. This callback function is called with a string parameter that contains the `visitId`.	function

Response

This method returns void.

The visitId is then available either:

As a parameter of the callback function (type: string)
As a global variable available in the page, called ifp_visitId

This method should called as soon as possible (when the loading of the first view for this use case starts).

ifp_initView

When the browser displays a new view to the customer, the following method must be called to initialize the profiling and to send the first profiling data to the signal collector:

...
   ifp_initView(visitId, partnersConfigurations, callback);
   ...

Method parameters

Parameter	Value	Description	Data type
`visitId`	Required	A previously generated `visitId` (from the `ifp_initUseCase` method)	string
`partnersConfigurations`	Required	A json object, containing the partner’s configurations (if needed). See below the partner section for integration with Threatmetrix for more information.	JSON object
`callback`	Optional	A javascript function that is called at the end of the `initView` function.	function

This method should be called after the loading of the view is complete. CORS

When you start a new use case, you should always call the ifp_initView method also.

Response

This method returns void.

ifp_initUseCaseAndView

This method is a shortcut that calls ifp_initUseCase then ifp_initView in sequence:

   ...
   ifp_initUseCaseAndView(partnersConfigurations, callback);
   ...

Method parameters

Parameter	Value	Description	Data type
`partnersConfigurations`	Required	A JSON object, containing the partner’s configurations (if needed). See below the partner section for integration with Threatmetrix for more information.	JSON object
callback	Optional	A javascript function that is called at the end of the `initUseCaseAndView` function. This callback function is called with a string parameter that contains the `visitId`.	function

Response

This method returns void.

ifp_finalizeView

Just before the user leaves a view or a page, the following method must be called. This method sends the latest information about this page to the signal collector:

   ...
   ifp_finalizeView(visitId, callback);
   ...

Method parameters

Parameter	Value	Description	Data type
visitId	Required	A previously generated `visitId` (from the `ifp_initUseCase` method)	string
callback	Required	A javascript function that is called at the end of the `finalizeView` function. This usually contains a function that sends the content of the view to your back end.	function

Response

This method returns void.

ifp_params

When the script is executed with the auto=1 option, the ifp_init methods are called automatically. In this scenario, it is not possible to directly pass a partner configuration object to these methods. To accommodate this, configurations can be set through a variable named ifp_params, which should be declared and initialized before calling the GAH script. This variable is used to configure the partners:

<head>...
    <script>
       var ifp_params = {
                bhv: {
                    pageIdCallback: function () {
                        return "ebanking/auth/login"
                    },
                    anonymous: {
                        by_name: ["userId"]
                    }
                }
            }
    </script>

    <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts?auto=1"></script>
    ...

Page ID

A page ID is a distinct numeric identifier assigned to a web page, essential for differentiating between multiple pages configured for page fingerprinting. Each page ID must be unique within the specified Org_ID. For example, if a customer operates multiple websites, each web page across all sites associated with that Org_ID must have a distinct page ID. This parameter links profiling tags to the page fingerprinting configuration.

Important consideration

If only a single page uses the page fingerprinting feature, specifying the page_id parameter within the profiling tags is not mandatory, although it is recommended. If the page_id parameter is omitted, the system defaults to a page ID of 1.

Additional recommendation

The inclusion of this parameter is strongly recommended for optimal usage. The value assigned to the page ID itself is arbitrary.

Parameter	Value	Description	Data type
`page_id`	Optional	Specifies which page is being profiled, applicable when more than one page contains ThreatMetrix tags. The value must be a whole number entered as a string and cannot contain `, .` or spaces.	string

Client applications can specify a page_id by invoking the following function:

ifp_initView({
  tmx: {
    page_id: 123
  }
});

The ifp_initView function is invoked to initiate data collection for a specific view. It loads the TMX script, optionally including a page_id if provided, and ensures the script is only loaded once per use case.

The tmx object manages the integration with ThreatMetrix within the application, controlling when and how TMX data collection scripts are loaded for each use case. It tracks whether profiling has already occurred and allows for re-profiling as needed.

Integration examples

This section provides complete integration examples for Framework v2 in different web application architectures:

Single-page application website

A single-page application (SPA) is a website that is composed of only one page, which dynamically loads the content of all other screens by doing ajax calls to the back end. Websites built with AngularJs, Angular, React, VueJS, and so on are usually SPA websites.

In a SPA, when the user browses the website, the header of the HTML page is never reloaded, and this is why Risk Management needs a dedicated script that does not need to be reloaded every time the user start a new use case.

Script integrations

The script should be included without any parameters in the header of the HTML page (the sooner, the better):

...
   <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts"></script>
...

First view of a use case

When the customer starts a new use case, a new visitId is generated. Because there is nothing specific to perform, the ifp_initUseCaseAndView shortcut can be used:

...
   ifp_initUseCaseAndView(conf, function(visitId){doSomethingWithTheVisitId(visitId);});
...

Then, just before the user leaves a view, the following method must be called. This method sends the latest information about this page to the signal collector:

...
   ifp_finalizeView(visitId, function(){loadTheNextView();});
...

All other views of the use case

When the browser displays a new view to the customer, the following method must be called to initialize the profiling and to send the first profiling data to signal collector:

   ...
   ifp_initView(visitId, conf);
   ...

Then, just before the user leaves a view, the following method must be called. This method sends the latest information about this page to the signal collector:

   ...
   ifp_finalizeView(visitId, function(){loadTheNextView();});
   ...

Multiple-page website

A multiple-page website is a website where the whole HTML page is reloaded when the user goes from one page to another (as opposed to a single-page application).

Script integration

The script can be included with the auto parameter, so that the data collection can start without any other development:

   ...
   <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts?auto=1"></script>
   ...

First view of a use case

When the use case starts, there is nothing to do because the auto parameter is set to 1.

Then, just before the user leaves the page, the following method must be called. This method sends the latest information about this page to the signal collector:

   ...
   <button type=”submit” onClick=”ifp_finalizeView(visitId, function(){return true});” />
   ...

All other pages of the use case

If the use case contains only one page, the front-end integration is complete.

If the use case contains several pages, then the script muar be included in each page with the previously generated visitId set as a parameter:

   ...
   <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts?auto=1&visitId=123456-789456"></script>
   ...

Optionally, you can also set the partners parameter to control which partner you want to include depending on the page. Then, as you did for the first page, just before the user leaves the page, the following method must be called:

...
   <button type=”submit” onClick=”ifp_finalizeView(visitId, function(){return true});” />
   ...

Because the ifp_initView method is called automatically, there is another way to send partners the configuration for this case. This is by declaring a global variable called ifp_params before inserting our script.

LexisNexis Threatmetrix and Behaviosec integration

You can integrate third-party partners using Framework v2.

LexisNexis offers a suite of products to authenticate and verify the identity of users:

LexisNexis Threatmetrix is a digital-identity intelligence platform that provides businesses with tools to authenticate and verify the identity of online users in real time.
The LexisNexis Behaviosec product provides a predictive behavioral biometric analysis solution.

Both products are accessible via one unique API called Dynamic Decision Platform (DDP).

The following steps are mandatory only if you are using the LexisNexis DDP service.

SSL hosting

This feature is mandatory to use ThreatMetrix collecting scripts. There is nothing to integrate in your page. It is only certificate and DNS configuration.

Fill in the related information in the onboarding form that your project leader provided to you.

Your project leader can guide you through the procedure, but the details are available in the ThreatMetrix knowledge base: https://portal.threatmetrix.eu/kb/index.htm#t=portal%2Fforensics%2Fintroduction_forensics.htm.

Here are the main steps:

Fill in the onboarding form.
Your project leader asks ThreatMetrix to generate a certificate signing request (CSR) with the completed onboarding information.
Your project leader gives you the generated CSR, so that you can use it to ask for a signed certificate from your preferred Certificate Authority.
Return this signed certificate to your project leader, so that it can be set up in the ThreatMetrix back end.
Your project leader provides you with a domain name returned by ThreatMetrix, so that you can set up an entry in our DNS.

Multi-page website integration

When integrating ThreatMetrix in a use case that contains several pages, collecting ThreatMetrix data is required only once per use case.

ThreatMetrix data can take time. It is recommended to choose the page on which the user spends the most time.

ThreatMetrix partners can be included only once per use case, by using the partner's parameter when integrating the GAH script.

DDP

The Dynamic Decision Platform (DDP) is a comprehensive solution that enables the integration of advanced behavioral biometrics into your application, without requiring the full ThreatMetrix platform. This platform allows for the real-time collection, analysis, and application of behavioral data to enhance security and improve the user experience.

Reset profile

Resetting a user profile is an important operation that ensures the accuracy of behavioral data in the system. This operation is typically required when a user profile was incorrectly trained due to anomalous events or implementation issues. Resetting the profile allows the system to start fresh and retrain the profile based on new, accurate data.

Reset a user profile in the following scenarios:

Incorrect training: The profile was trained during a period when the user was not exhibiting normal behavior (for example, during a scam or due to implementation errors).
Behavioral anomalies: There are significant and persistent anomalies in the user's behavior that suggest the profile does not accurately reflect the user.

To reset a user profile, an API call is made with two parameters: userId and target. Depending on the value of target, the API call can either reset the entire profile or just the password-related behavioral data.

Parameter	Value	Description	Data type
`userId`	Required	The unique ID of the authenticated user that is mapped to the `account_login` query parameter.	string
`target`	Optional	The target profile to reset. If null, reset the entire profile using `event_type=reset_user_profile`. If set to `password`, reset only the password using `event_type=password_reset`.	string

BehavioSec

The following steps are mandatory only if you are using the BehavioSec service. Otherwise you can skip this section.

To add the BehavioSec analysis to your page, an extra configuration step is required. It consists of the following:

Declare the page identifiers in the BehavioSense dashboard.
Customizing your HTML pages to list the fields that should be anonymous or excluded from the BehavioSec analysis, if any.

Page declaration

The pages for which BehavioSec must be implemented must be declared in the BehavioSense dashboard (in the menu settings > page definitions).

Every single page analyzed must be declared. This includes both HTML web pages and mobile application pages.

See the documentation for a detailed description of the BehavioSense dashboard.

Thales provides the credentials for the sites mentioned above when the onboarding process is complete.

New account originating use case

To set up a page for new account originating, the page definition must follow a set of specific rules.

The page definition MUST disable anomaly detection.
For each field on your page:
- Your type c (movement) fields MUST disable Remote Access detection reason 5.
- Your fields MUST set Ignore to True. This prevents BehavioSense from calculating a behavioral score for the specific user associated with this target.
Your fields MUST set the New Account Fraud target to True.

See the documentation for a detailed description of configuring page definitions to use new account fraud.

Page customization

If you have data that must be kept confidential, then you can use masked and anonymous types. The masked type is preferred from an analysis perspective (for example, for RAT detection), but in some scenarios it might not be considered confidential enough, because it does not mask keys like shift, control, and so on.

Anonymous fields We recommend making every input field of type password anonymous. Other fields can also be made anonymous. These fields can be identified either by their name, ID, or type.
- ONLY set static input fields as anonymous. These are fields where the input never changes for each user, such as password fields.
- Be careful about setting anonymous for any type of field where the input changes will not work.
- If a password field is configured as anonymous and the password is changed, then the profile for that target of that user must be reset.
Masked fields You can use the masked type as an alternative to the anonymous type when the data doesn’t have to be kept strictly confidential. Using the masked type provides more information from an analysis perspective.
Ignored fields It is also possible to configure a deny-list of fields that should not be monitored. In this case, you can identify them either by their ID or name.
PageId There is a mapping on the server side to analyze the behavior of the end user on your page. This mapping is based on the pageId. You define the pageId param in the Behaviosec configuration for each page or view. It is important to define this ID if you want to set some weight to the different fields of your pages.

There are two solutions for setting the Behaviosec configuration of the view:

For a multi-page website

You can set the ifp_params variable with the configuration, before including our script:

 <head>...
    <script>
       var ifp_params = {
                bhv: {
                    pageIdCallback: function () {
                        return "ebanking/auth/login"
                    },
                    anonymous: {
                        by_name: ["userId"]
                    }
                }
            }
    </script>

    <script src="<%= signalCollectorUrl %>/api/v2/tenants/<%= tenantId %>/scripts?auto=1"></script>
    ...
</head>

If the use case contains several pages, this ifp_params variable must be set on every page (with the page’s specific configuration).

Behaviosec multi-page implementation can have a significant impact on the getDecision performance.

For a single-page application

The Behaviosec configuration can be sent directly through the ifp_initView or ifp_initUseCaseAndView methods:

Ifp_initView(visitId,  {
                bhv: {
                    pageIdCallback: function () {
                        return "ebanking/auth/login"
                    },
                    anonymous: {
                        by_name: ["userId"]
                    }
                }
            });

If the use case contains several views, this must be done on every view (with the view’s specific configuration).

The Behaviosec multi-page implementation can have a significant impact on the getDecision performance.

Suggest A Change

Web framework v2

Script integration

Endpoint

Request parameters

Response messages

ifp_initUseCase

Method parameters

Response

ifp_initView

Method parameters

Response

ifp_initUseCaseAndView

Method parameters

Response

ifp_finalizeView

Method parameters

Response

ifp_params

Page ID

Important consideration

Additional recommendation

Integration examples

Single-page application website

Script integrations

First view of a use case

All other views of the use case

Multiple-page website

Script integration

First view of a use case

All other pages of the use case

LexisNexis Threatmetrix and Behaviosec integration

SSL hosting

DDP

Reset profile

BehavioSec

Page declaration

New account originating use case

Page customization

For a multi-page website

For a single-page application

On this page