How to Integrate the Kount Web Client for Device Data Collection into Your Website

Kount fraud prevention solutions are designed for simple integration – once you have signed up and  have a client ID, just add the Web Client SDK to your website using these instructions, and your site will be equipped for our anti-fraud features. The Kount SDK is a key component that communicates with the other segments in the Kount fraud prevention ecosystem to keep your system safe and reliable.

This article contains installation and usage instructions for configuring the Web SDK on your website. The Kount SDK must either be bundled in the website using NPM/Yarn or included via static <script> tags in HTML. Kount recommends using NPM to install the SDK and keep it up to date; however, static versions are available on GitHub if NPM is unavailable for your website.

Restrictions and Security

The SDK must be:

• Served from the same domain as the website address rendering in the user’s browser
• Kept current as new versions are released
• Used within the context of a web browser

The SDK must NOT be:

• Modified
• Used server-side
• Used outside the context of a web browser

Integrity Checksums (SRI Hashes)

To verify the integrity of the downloaded files, you can log into the Kount Developer site to review the integrity checksums of the files.

Data required to configure the SDK

The following data is required to use the kount-web-client-sdk:

environment

• Use a value of TEST if executing against the test environment.
• Use a value of PROD if executing against the production environment.

clientID

• The unique value provided by Kount to customers during initial account setup
• A static value that does not change across executions or environments
• Previously known as “merchantID” for some customers

isSinglePageApp

• Boolean value of true or false
• Used to specify if the SDK is executing in the context of a Single Page Application (SPA)

sessionID

• 32-character strings generated by you; these need to be random/unpredictable
• Must remain unique to the originating user website visit and cannot be reused for a minimum of 30 days
• Contains only alphanumeric characters, dashes, or underscores (0-9, A-Z, a-z, - and _)

Session IDs and Kount Command

Web Session ID and Kount Session ID are not always the same. The Web Session ID is your system's unique identifier for the session. The Kount Session ID is the session ID you generate and use to identify a session in the Kount DDC and Kount API endpoints. Depending on how your Web Session performs, you might need to generate a unique Kount Session ID for the Kount DDC (this SDK).

The Kount Session ID must be unique for every RIS post, even when multiple transactions occur in the same Web Session. This means that the SDK setup must be re-invoked with a new Kount Session ID for every transaction.

Session IDs and Kount Control

The Kount Session ID can be repeated within the same Web Session.

For example, multiple login attempts in a short time window (less than 15 minutes) can use the same Kount Session ID. In this case, the DDC does not need to be restarted every time.

For more information on Session IDs, review How to Create a Session ID for the Device Data Collector.

Installing the Client SDK

NPM Package

If you are developing your own website, use the NPM package from the directory containing your package.json:

# Using NPM
npm install @kount/kount-web-client-sdk
    
# Using Yarn 
yarn add @kount/kount-web-client-sdk

Static/Browserfied file from GitHub

Obtain the Browserfied SDK from the Kount GitHub repository, add this file to your website, and then proceed to Using the SDK.

Configuration

Base configuration and invoking the SDK

Kount provides a template object on Github illustrating the required format of the config object.

Example:

var kountConfig = {
"clientID": "999999", // clientID assigned to you by Kount   
"environment": "TEST", // Environment for data collection provided by Kount
"isSinglePageApp": false // Or true, changes some internal behavior
}

Optional Lifecycle Callbacks

The Web Client SDK provides a callback system that allows you to execute custom code at certain points in the data collection process. You can increase the kountConfig object to contain one or more life cycle hooks with a function (or lambda) of your choice. There are two main hooks:

• collect-begin – Triggers when the collection starts
• collect-end – Triggers after the collection ends

When executed, the callback functions are given one parameter; a JavaScript object containing the following properties:

• sessionID: string – The sessionID you generated for the kountConfig object
• KountClientID: string – The clientID (previously known as merchantID for some clients)

Example of adding optional callbacks (with arbitrary callback code) to the kountConfig object set up in base configuration:

kountConfig.callbacks = {
        'collect-begin': function (params) {
            // Any code you'd like to execute on collection start,
            //     such as quietly adding the session ID to your login form!
            var loginForm = document.forms['loginForm'];
            var input = document.createElement('input');
            input.type = 'hidden';
            input.name = 'kaId';
            input.value = params['SessionID'];
            loginForm.appendChild(input);
        },
        'collect-end': function (params) {
            // Any code you'd like to execute when we're done collecting data
            loginButton = document.getElementById('login_button');
            loginButton.removeAttribute('disabled');
        }
    };

Optional Debug Logging

If additional SDK logging is needed during SDK integration troubleshooting, an optional isDebugEnabled boolean node can be set to true within the configuration object passed into the kountSDK function.

When this value is set to true more verbose SDK logging should appear in the browser console.

Example:

let kountConfig = {
        clientID: "YOUR_CLIENT_ID",
        environment: "TEST_OR_PROD_DEPENDING_ON_THE_ENVIRONMENT",
        isSinglePageApp: true,
        isDebugEnabled: true,
    };

Integrating the SDK

When to use the SDK

Kount recommends that you add the kount-web-client-sdk on all core pages in your site’s workflow, particularly pages that lead to vulnerable actions (purchase, payment, security changes, contact info updates, etc.). After the kount-web-client-sdk is invoked once (and completed) on a page of your website, no further SDK interaction is required for that page and collection is now automatic.

Invoking the SDK and starting collection

Start executing the kount-web-client-sdk by invoking its exported kountSDK function with the appropriate arguments. As of version 1.1.4, the function signature is as follows:

function kountSDK(kountConfig, sessionID)

Both parameters are required:

• kountConfig – The configuration JavaScript object detailed in base configuration
• sessionID – The sessionID you generated for this user’s website visit

To enable data collection, use the example below:

// In-browser example to invoke the SDK
<script src="./path/to/kount-web-client-sdk-bundle.js" type="module"></script>
<script>
      const sessionID = getSessionIDorGenerateOne();
      const kountConfig = { /* Configured as above */ };
      const sdk = kountSDK(kountConfig, sessionID);
      if (sdk) {
         // Any non-blocking post-initialization logic can go here
         console.log("Anti-fraud SDK activated!");
      }
</script>

Optional IsCompleted() status check (DEPRECATED)

Due to the asynchronous nature of the device collection process, the status of the collection is not known until the SDK has been invoked. The IsCompleted() function returns a boolean that indicates if the collection has completed (true) or not (false), and it can be called from the SDK object returned from kountSDK(kountConfig, sessionID).

// In-browser example to invoke the SDK
<script src="./path/to/kount-web-client-sdk-bundle.js" type="module"></script>
<script>
            const sessionID = getSessionIDorGenerateOne();
            const kountConfig = { /* Configured as above */ };
            sdk = kountSDK(kountConfig, sessionID);
            // SDK is an object with this function if initialization succeeds
            if (sdk) {
                // Any non-blocking post-initialization logic can go here. For example:
                console.log("Anti-fraud SDK activated!");
                function monitorIsCompleted() {
                    console.log(`IsCompleted()=${sdk.IsCompleted()}`);
                }
                monitorId = setInterval(monitorIsCompleted, 500);
                function stopMonitor() {
                    clearInterval(monitorId);
                    console.log("Monitor stopped");
                }
                setTimeout(stopMonitor, 5000);
                // Finished collecting!
            }
        </script>

Additional Examples

Using React with the NPM-installed SDK:

import kountSDK from '@kount/kount-web-client-sdk';
        import React, { useState } from 'react';
        function Example() {
            const [sessionID, setSessionID] = useState('');
            const clientID = 900900;
            async function onDoCollectionClick() {
                let kountConfig = {
                    clientID: "YOUR_CLIENT_ID",
                    environment: "TEST_OR_PROD_DEPENDING_ON_THE_ENVIRONMENT",
                    isSinglePageApp: true,
                };
                let sessionID = identifyTheSessionID();
                kountSDK(kountConfig, sessionID);
            }
            return (
            <div>
                <button onClick={onDoCollectionClick}>Do Collection</button>
            </div>
            );
        }

Testing

When testing your integration with the kount-web-client-sdk, you must not test new features or run load tests against Kount production environments. Specify an appropriate TEST environment value in the JavaScript configuration object that you pass into the SDK invocation. Contact your Customer Success Manager for more information.

Troubleshooting

Kount SDK outputs messages to the browser web console at different levels. Refer to the SDK code on GitHub to identify console messages that might help you during configuration.

Additional notes

RIS Integration with our customer SDK

If you are using the Kount RIS Service, following successful browser invocations of the kount-web-client-sdk, client-initiated server-side calls to RIS (using the same clientID and sessionID that were specified during the SDK executions for a user’s website visit) should result in the documented RIS functionality.

Static Web SDK Sequence Diagram

This diagram summarizes the relationships and interactions between the customer’s browser, the client’s site, the client-hosted kount-web-client-sdk, and the Kount-defined endpoints.