📘

Before you start

Make sure you've obtained a token, server URL, and auth key from credolab Customer Success Manager.

How the Web SDK Works

The Web SDK collects behavioral data from your users' web sessions and uploads it as a dataset to credolab servers.
The integration flow is:

1. In your system, create a unique reference number for the user or session.
   This is how credolab links the collected dataset to your record.
2. Instantiate CredoAppService or CredoAppServiceAsync (see Which service should I use? below).
3. Call startTracking on the pages or user journeys you want to capture, for example a loan application form.
4. Optionally call stopTracking to pause collection, e.g. when the user leaves the target flow.
5. Call stopTrackingAndCompleteAsync to finalize. This stops tracking and uploads the dataset to credolab servers. This step is always required.

Which service should I use?

The SDK provides two service classes:

CredoAppService is for single-device, single-session tracking. Data is stored locally during the session, and the reference number is passed at the end when you call stopTrackingAndCompleteAsync(referenceNumber). Use this when the user completes the entire journey on one device.

CredoAppServiceAsync is for cross-device and cross-platform tracking. Data is continuously uploaded to the server, and the reference number is passed upfront into startTrackingAsync(referenceNumber). Use this when the user may switch between devices, browsers, or platforms (e.g. starts on mobile, finishes on desktop). Multiple sessions are linked by the same reference number.

⚠️

Note

With CredoAppServiceAsync, you are responsible for associating the reference number with your user (e.g. after login). Because the reference number is provided at the start, the SDK can link sessions across multiple devices independently.

🚧

Tracking Limitations

The Web SDK may not capture behavioral events in the following scenarios:

• When JavaScript is disabled in the client’s browser
• Events occurring inside <iframe> elements due to browser restrictions
• Interactions within <canvas> elements

1. Declare dependencies

As the private registry is used, you'll need to add to your user or project .npmrc file (if this file is absent you have to create it alongside the package.json file) the following:

❗️

Token Replacement Instructions

Kindly note that exclusively the occurrence of $TOKEN with the $ symbol must be substituted with the provided key. The expression :username=token is to be retained in its original state.
For yaml $TOKEN has to be decoded from base64 format.

@credolab:registry=https://npm.cloudsmith.io/credolab/common-sdk/
//npm.cloudsmith.io/credolab/common-sdk/:username=token
//npm.cloudsmith.io/credolab/common-sdk/:_password=$TOKEN

nodeLinker: node-modules

npmScopes:
  credolab:
    npmRegistryServer: "https://npm.cloudsmith.io/credolab/common-sdk/"
    npmAlwaysAuth: true
    npmAuthIdent: "token:$TOKEN"

Important: Always exclude .npmrc files from version control (e.g., add them to .gitignore). These files may contain sensitive authentication tokens or private registry credentials that should never be committed to the repository.

Run the following command in a terminal to install SDK:

npm install '@credolab/[email protected]'

npm install '@credolab/[email protected]'

Alternatively, you can add it to the dependencies section in your project package.json file

{ "dependencies": 
	{ "@credolab/credoapp-sdk": "$version" } 
}

{ "dependencies": 
	{ "@credolab/credoapp-iovation-sdk": "$version" } 
}

and then execute thenpm install command in the terminal.

⚠️

Note

Replace $TOKEN with actual token obtained from credolab

Also, replace X.Y.Z with module versions from Web SDK page.
The final result should look like this:

	npm install '@credolab/[email protected]'

add import declaration for CredoAppService or CredoAppServiceAsync

import { CredoAppService } from "@credolab/credoapp-sdk";

import { CredoAppServiceAsync } from "@credolab/credoapp-sdk";

import { CredoAppService } from "@credolab/credoapp-iovation-sdk";

import { CredoAppServiceAsync } from "@credolab/credoapp-iovation-sdk";

2. Build and use the SDK

Choose the tab that matches your use case. See Which service should I use? above if you're unsure.

      // CredoApp authentication key provided by credolab team
      var authKey = "AUTH_KEY"
      // value from CredoLab URLs table
      var url = "https://scoring-**.credolab.com";

      // Step 1: Instantiate the service
      var credoAppService = new CredoAppService(url, authKey);

      // Step 2: Start tracking when the page loads or the user begins the target flow
      // Data is stored locally on the device at this point
      credoAppService.startTracking();

      // Step 3 (optional): Pause tracking if needed (e.g., user leaves the target flow)
      function stopTracking() {
        credoAppService.stopTracking()
      }

      // Step 4: Stop tracking and upload the dataset to credolab servers
      // The reference number is passed here — it links this dataset to your internal record
      function collectData() {
        var referenceNumber = "UNIQUE_REFERENCE_NUMBER";
        credoAppService.stopTrackingAndCompleteAsync(referenceNumber).then(() => {
          alert("Dataset has been uploaded and completed");
        }, (e) => alert(e));
      }
 

      // CredoApp authentication key provided by credolab team
      var authKey = "AUTH_KEY"
      // value from CredoLab URLs table
      var url = "https://scoring-**.credolab.com";

      // Step 1: Instantiate the service
      var credoAppService = new CredoAppServiceAsync(url, authKey);

      // Step 2: Start tracking with the reference number upfront
      // Data is continuously uploaded to the server — this allows linking sessions
      // across multiple devices, browsers, and platforms using the same reference number.
      // The dataset will appear with "incomplete" status on the dashboard.
      var referenceNumber = "UNIQUE_REFERENCE_NUMBER";
      credoAppService.startTrackingAsync(referenceNumber).then(() => {
        alert("Event tracking started and dataset continuously uploaded");
      }, (e) => alert(e));

      // Step 3 (optional): Pause tracking if needed
      function stopTracking() {
        credoAppService.stopTrackingAsync().then(() => {
          alert("Event tracking stopped");
        }, (e) => alert(e));
      }

      // Step 4: Stop tracking and mark the dataset as completed
      // Once called, the dataset status changes to "completed" and a score can be generated.
      function collectData() {
        credoAppService.stopTrackingAndCompleteAsync().then(() => {
          alert("Dataset has been completed");
        }, (e) => alert(e));
      }

❗️

Please note that it is not possible to start tracking with a new reference number if there is already ongoing tracking associated with another number. In such cases, an error will be returned, indicating that tracking for a certain reference number is currently in progress. To start tracking with a different reference number, the current tracking process must be stopped on the instance that initiated the tracking process.

🚧

Assign stable, unique identifiers to key user interactions so the Credolab SDK can accurately map them to meaningful events. Add id attribute to the element. For example:

HTML

 <!DOCTYPE html>
<html>
<head>
    <title>Application form</title>
</head>
<body>
    <!-- Button with an ID -->
    <button id="submit_button">Click me</button>

    <!-- Input element with an ID -->
    <input type="text" id="first_name_input" placeholder="Enter your first name"/>

</body>
</html>

Next Steps

After successfully integrating our SDK, it is recommended to proceed with the following steps to utilise our platform effectively:

1. Setting up your Reverse Proxy
2. Test and collect your Dataset Insights or TruValidate Fraud Check(Iovation Fraud Check) to assess risk based on the device and transaction details provided.

If you have any further questions, please do not hesitate to contact us.

Video Tutorials

React Application Integration Tutorial

Angular Application Integration Tutorial