How to Integrate the Kount Web Client SDK 1.1.4 into Your Website (ARCHIVED)

Integration with Kount's fraud prevention solutions requires that your website(s) integrate with Kount by using Kount's Web Client SDK (version 1.1.4) JavaScript. This JavaScript executes while your user's web browser renders your website.

You must obtain, host, and serve the kount-web-client-sdk, as well as properly invoke the SDK when customers render your website.

Using the Node Package Manager

The kount-web-client-sdk is a Kount-supplied JavaScript SDK that is an integral component for the Kount integration, as it communicates with the other components in Kount's fraud prevention ecosystem.

Kount periodically releases new versions of the kount-web-client-sdk, so it is best practice to keep up-to-date with the latest release – earlier versions can become deprecated and unsupported.

The kount-web-client-sdk is available in the following ways:

1. Download a versioned release of the kount-web-client-sdk.js from GitHub.
2. Use your preferred Node Package Manager to install the latest kount-web-client-sdk package.

   npm installation

   $ npm install @kount/kount-web-client-sdk

   yarn installation

   $ yarn add @kount/kount-web-client-sdk

3. To verify the integrity of the downloaded files, review the checksums.
   
   Note: Review the code prior to use according to your policies.

Using the Browserfied file from GitHub

Obtain the Browserfied SDK from the Kount GitHub repository.

Requirements/Restrictions

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

Data Required by the SDK

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

hostname

• Provided by Kount to clients during initial account setup
• Specific to environment
• Used to specify the Kount hostname that will be used to process the SDK's requests

If you do not know which Kount hostname you should use, please contact your Kount representative.

clientID

• Provided by Kount to clients during initial account setup
• Unique to each Kount client
• Static value that does not change across executions or environments

If you don't know your clientID, contact your Kount representative.

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

• Must remain unique to the originating user website visit (not be reused) for a minimum of 30 days
• Contain only alphanumeric characters (0-9, a-z, or A-Z), dashes (-) or underscores (_)
• 32 characters in length
• Random/unpredictable

For Kount Command

Web Session ID and Kount Session ID are not necessarily the same. The Web Session ID is your own 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 behaves, you might need to generate a unique Kount Session ID for the Kount DDC.

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 DDC does need to be rerun and a new Kount Session ID generated for every transaction.

For 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 rerun every time.

Optional Configuration Values

The Web Client SDK provides a client programmable callback system that allows the client to execute custom code at certain points in the data collection process. This method allows a merchant to add a callback function to be called at a specified life-cycle hook. A merchant can pass a JavaScript object containing one or more life cycle hooks with a function pointer or an anonymous function to be executed.

List of hooks (in order of firing):

• collect-begin (triggers when the collection starts)
• collect-end (triggers when the collection ends)

When executed, the callback function is passed a JavaScript object containing the following properties:

• SessionID (the session ID used in the collection)
• KountClientID (the merchant ID)

Configure and Test the SDK

Incorporate and execute the kount-web-client-sdk on all pertinent pages of your website. Pertinent pages include 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 (and subsequently completes execution) on a page of your website, no further SDK interaction is required for that page.

Configuring

The kount-web-client-sdk invocation requires a JavaScript object that specifies the SDK's configuration specific to your implementation. This project includes a JavaScript object literal notation example that creates a JavaScript object containing all the required fields for kount-web-client-sdk configuration as kount-web-client-config-template.js. This provided example specifies generic values that must be updated with values appropriate to your specific implementation. Each individual SDK configuration property is further explained in the Data Required by the SDK section above.

You should create similar JavaScript objects to appropriately configure your application's use of the SDK. For example, if you are going to test your implementation, you must adjust your application's SDK configuration for hostname to point at the appropriate Kount, non-production, testing hostname.

Invoking

Start executing the kount-web-client-sdk by invoking its exported kountSDK function with the appropriate arguments.

The function is defined as:

function kountSDK(config, sessionID)

The required parameters are:

• config: the configuration JavaScript object created as per the Configuring section above.
• sessionID: the sessionID you generated for this user's website visit. Execution as a Module.

NPM Installed SDK Examples

Execution – Importing the SDK

import kountSDK from '@kount/kount-web-client-sdk';

import React, { useState } from 'react';

function Example() {

const [sessionID, setSessionID] = useState('');

const merchantID = 900900;

async function onDoCollectionClick() {

let kountConfig = {

clientID: "YOUR_CLIENT_ID",

hostname: "YOUR_KOUNT_HOSTNAME",

isSinglePageApp: true,

};

let sessionID = identifyTheSessionID(); // A client-supplied mechanism to identify the appropriate value for the sessionID.

kountSDK(kountConfig, sessionID);

}

return (

<div>

<button onClick={onDoCollectionClick}>Do Collection</button>

</div>

);

}

Hosted JavaScript File SDK

Execution – Configuration with Template

<script type="text/javascript" src="./kount-web-client-config-template.js"></script><!--Modify the src location according to where you are hosting the JavaScript code that creates an appropriate JavaScript object for configuration. This example assumes the creation of an object named kountConfig.-->

<script type="text/javascript" src="./kount-web-client-sdk-bundle.js"></script><!--Modify the src location according to where you are hosting the kount-web-client-sdk-bundle.js-->

<script type="text/javascript">

const sessionID = identifyTheSessionID(); // A client-supplied mechanism to identify the appropriate value for the sessionID.
kountSDK(kountConfig, sessionID); // Start the execution.

</script>

Execution – Configuration with Object Literal

<script type="text/javascript" src="./kount-web-client-sdk-bundle.js"></script><!--Modify the src location according to where you are hosting the kount-web-client-sdk-bundle.js-->

<script type="text/javascript">

const sessionID = identifyTheSessionID(); // A client-supplied mechanism to identify the appropriate value for the sessionID.

//Create the JavaScript object for configuration using JavaScript object literal notation.

const kountConfig = {

"clientID": "YOUR_CLIENT_ID;", // Replace YOUR_CLIENT_ID with your Kount provided clientID.

"hostname": "YOUR_KOUNT_HOSTNAME", // Replace YOUR_KOUNT_HOSTNAME with the appropriate hostname.

"isSinglePageApp": false // false or true depending on whether your website is a Single Page Application.

};
kountSDK(kountConfig, sessionID); // Start the execution.

</script>

Configuring Callbacks Example

kountConfig.callbacks = {
    'collect-end':function (params) {
    loginButton = document.getElementById('login_button');
    loginButton.removeAttribute('disabled');
    },'collect-begin':function (params) {
        var loginForm = document.forms['loginForm'];
        var input = document.createElement('input');
        input.type = 'hidden';
        input.name = 'kaId';
        input.value = params['SessionID'];
        loginForm.appendChild(input);
    },
};

IsCompleted function

Due to the asynchronous nature of the device collection process, the status of the collection is not immediately known until the kount-web-client-sdk has been invoked. The IsCompleted() function returns a boolean that indicates if the collection has completed or not.

Testing

When vetting your integration with the kount-web-client-sdk, you must not test functionality or run load tests against Kount's production hostnames; rather, you should specify an appropriate test hostname for the hostname value in the JavaScript configuration object that you pass into the SDK's invocation.

Troubleshooting

kount-web-client-sdk outputs messages to the browser's web console at different levels.

Refer to the kount-web-client-sdk code to identify console messages that might prove useful for your specific situation.

Make sure your web console is configured to display the appropriate level for the messages you are attempting to see.

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.

The SDK and RIS

If you are using Kount's 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.