Table of contents
Issuer uSDK v6.6 (beta)
The Issuer uSDK 6.6 for Browser is a javascript library that helps issuers (ACSes, etc) to perform various advanced actions during 3DS Method and/or 3DS Challenge flow. For instance an issuer can instruct the uSDK to save a device ID/tag (sort of a cookie) during 3DS Method and then read the tag during consequent transactions.
Overview
The instructions
An instruction is an action that an issuer prescribes the uSDK to perform (and return a result) during the next 3DS transaction. Typically the uSDK persists instructions received in transaction A (either during 3DS Method or a Challenge Flow) so they can be executed and their results obtained during transaction B.
The following instructions are currently supported:
Instruction | Description |
---|---|
DeviceID | Saves an identifier in the browser. The identifier is then delivered back to the issuer on the next transaction |
GetDeviceAttributes | Captures a basic browser fingerprinting information |
CaptureBehavioralBiometrics | Captures the behavioral metrics such as typing cadence, mouse movements etc while the user is interacting with a challenge screen |
Storing the instruction(s)
An issuer is supposed to form a special javascript object which contains one or more instruction and pass it to storeInstructions
API method the uSDK exposes. The uSDK persists the instructions in the user’s browser so that the data lives through browser restarts. The data format for the instructions is shown below:
{
"name": "com.msignia.usdk",
"id": "com.msignia.usdk",
"criticalityIndicator": false,
"data": {
"DeviceID": { "v": 1, "value": "18d7c8" },
"GetDeviceAttributes": { "v": 1 },
"CaptureBehavioralBiometrics": { "v": 1 },
}
}
In the example above there’re three instructions passed - DeviceID
, GetDeviceAttributes
and CaptureBehavioralBiometrics
. Up on receiving such a set of instructions the uSDK stores them internally but does not execute any of them just yet. It needs to be told to execute the stored instructions as shown in the next section.
There’s usdk.storeInstructions(instructions)
method the uSDK has for the purpose, it is documented further in this document.
Executing the instructions
The uSDK exposes two ways of executing stored instructions. The first one is an instant one - it executes the instructions and returns the results of the executiion:
usdk.executeInstructions()
.then(executionResult => {
console.log("Received: ", executionResult);
});
The second way should be employed when one or more instruction stored previously were supposed to capture user interaction. The challenge flow is a good example of this case - one would want the uSDK to start capturing behavioral biometrics right before user begins to type an answer in the text field and finish capturing when the user finishes doing that by clicking a SUBMIT button:
// tells the uSDK to begin executing CaptureBehavioralBiometrics thus capruting typings/mouse events
usdk.startExecutingInstructions({});
// enable the challenge form so that user can start interacting with it
challengeForm.enabled = true; // this is a schematic code
function submitChallenge() {
usdk.finishExecutingInstructions()
.then(executionResult => {
console.log("Received: ", executionResult);
});
}
As shown above, the two methods - startExecutingInstructions
and finishExecutingInstructions
need to be called in order.
The example shows the results of the two instructions - DeviceID
and CaptureBehavioralBiometrics
executed by the uSDK. Each of the instructions defines its own result format. See the documentation for each of the instructions further in this document.
Integrating the uSDK
Since the issuer uSDK is still in beta one has to contact an mSIGNIA administrator to obtain it. Normally it is shipped as a single javascript file which is refered to as usdk.js
further in the document.
mSIGNIA administrator will provide the customer with a license key for the uSDK. The license key should be passed to the uSDK at initialization time as shown later in this document.
Once the file is obtained, it has to be included in a web page like the following:
<script src="https://some-issuer-backend.com/usdk.js"></script>
The an instance of uSDK is recommended to be created like this:
const usdk = new Usdk({
licenseKey: "<the license key issued by the administrator>",
logLevel: "INFO", // DEBUG | INFO | WARN | ERROR
});
And finally the uSDK should be initialized:
Then it has to be initialized:
usdk.initialize().then(() => {
console.log("uSDK initialized successfully!");
}).catch((error) => {
console.log("uSDK failed to initialize, error: ", error);
});
Executing uSDK methods
Store instructions
The storeInstructions
is used when ab issuer wants the uSDK to store one or more instructions. Once an instruction is stored, the uSDK will be able to execute it within the same or future transaction.
usdk.storeInstructions(instructions);
The instructions
argument can be one of the following:
- A base64 encoded string that once decoded and JSON parsed will yield a javascript object documented in the
Storing the instruction(s)
in the beginning of this document - A javascript object as per
Storing the instruction(s)
in the beginning of this document
The method does not return any result, it is void
thus.
Execute instructions
As it’s been explained in the Overview - Executing the instructions, there are two possible ways running the instructions - an instant one and a continuous one. When one of the two ways are called, the uSDK recalls all stored instructions and executes them. The result of their execution is then compiled and returned back to the caller.
An instant execution
usdk.executeInstructions()
.then(executionResult => {
console.log("Received: ", executionResult);
});
This will cause the uSDK to execute all instructions it has previously stored, combine their results into a resulting object and return it back.
A continuous execution
usdk.startExecutingInstructions({});
// then after some time or up on certain event:
usdk.finishExecutingInstructions()
.then(executionResult => {
console.log("Received: ", executionResult);
});
The result
The execution result is an object whose keys are the instruction names the SDK has executed and the values are the values those instructions captured/resulted with. Here’s an example:
{
"CaptureBehavioralBiometrics": { "v": 1, "data": "[\"mm\",87,328,461],[\"mm\",103,318,467]..." },
"DeviceID": { "v": 1, "data": "ce2a86" }
}
Instructions reference
DeviceID
Instruction
Using the DeviceID
instruction an issuer can tell uSDK to store certain indentifier in the user’s browser and return it back when executeInstructions
is called during a consequent transaction.
Store
So, to store such an instruction, the following object needs to be passed to uSDK’s storeInstruction
method:
{
"name": "com.msignia.usdk",
"id": "com.msignia.usdk",
"criticalityIndicator": false,
"data": {
"DeviceID": { "v": 1, "value": "18d7c8" },
}
}
In the example above, the uSDK will store the value of 18d7c8
in the user’s browser.
Execute
When executed using either instant or continuous routine, the following result is returned:
{
"DeviceID": { "v": 1, "data": "18d7c8" }
}
GetDeviceAttributes
Instruction
The executing result executing of the GetDeviceAttributes
instruction is a set of browser device fingerprinting attributes as per 3DS 2.2 specification.
Store
{
"name": "com.msignia.usdk",
"id": "com.msignia.usdk",
"criticalityIndicator": false,
"data": {
"GetDeviceAttributes": { "v": 1 },
}
}
Note, there’s no arguments except of the version (v
) in the object.
Execute
The execution result is then looks like the following:
{
"GetDeviceAttributes": { "v": 1,
"data": {
"browserColorDepth": "24",
"browserScreenWidth": "2400",
// other attributes go below...
}
}
}
CaptureBehavioralBiometrics
Instruction
This instruction tells uSDK to capture behavioral biometric while user interacts with the UI. This instruction should only be executed using the continous flow - startExecutingInstructions
and then after a while the finishExecutingInstructions
- because it takes a while while the user interacts so the uSDK needs to exactly know when to start executing and when to finish that.
Store
{
"name": "com.msignia.usdk",
"id": "com.msignia.usdk",
"criticalityIndicator": false,
"data": {
"CaptureBehavioralBiometrics": { "v": 1 },
}
}
Execute
{
"CaptureBehavioralBiometrics": { "v": 1, "data": "ptypes:{mouse:130},k229:0,kn:0,tz:-180,pr:2,u..." }
}
Sample Issuer Apps
There’re two sample backends implemented and exposed to help an issuer to grasp the concepts easier. The one is a sample backend that shows what an ACS backend would need to do in order to integrate and leverage the issuer uSDK. The other one is a sample merchant backend that shows how it is recommended to maintain the 3DS Method as well as Challenge iFrames as well as how to implement the notification callbacks.
- Sample ACS backend: https://qa-issuer-sample-acs.msignia.com
- Sample Merchant backend: https://qa-issuer-sample-merchant.msignia.net
The backends are configured to talk each to the other. Per request, mSIGNIA may provide the source codes of the backends.