🖥️JavaScript Programming

Project Setup

These instructions assume a development methodology leveraging traditional web programming (html and javascript, etc.); the AuthenticAction™ SDK is added to your web project through declaration of a script library in pages using the SDK.

Script Declaration:

To start using AuthenticAction™ in your page(s), first declare the script in your html, as follows

you'll need to install it in your project. You can do this by including a script tag that you get in your integration setup.

<script src="<AuthenticAction SDK CDN URL>" defer></script>

Note: the exact name and version of the script library in your project may slightly differ, and is listed here as an example. As part of your organizations integration startup package, you will be supplied with various SDK connectivity information, including an organization key and access to the applicable version of the .js library for your project.

JS SDK Initialization:

Now that you have the SDK declared in your page(s) within your project, you can start using it by adding some simple code within the page.

The first thing you'll need to do is initiate the Ironvest Class with your selected option configuration. During declaration of a new IronVest instance, you will pass in the organizationKey, csid and uid.

cid

You must have the cid (ClientId) provided by IronVest to be used with the SDK.

Note: As part of your organizations integration startup package, you will be supplied with various SDK connectivity information, including an client ID and an api key.

csid

Please note that you have to create your own application Session ID to initiate the IronVest SDK's session. An Ironvest instance is usually associated with a user's login session and is used to correlate the actions performed to a particular user. It's possible to create a new scope by setting a new Session ID by calling setCsid() or by creating a new Ironvest instance.

A description of the CSID can be found under the Components and Considerations section.

uid

Setting the UID provides context to the unique session, and associates the session activity with a specific user.

A description of the UID can be found under the Components and Considerations section.

For more information about the options, see the Components and Considerations section. For more information about what data is being collected, see the The AuthenticAction Data section.

const options = {
    cid: constants.clientId, //  Provided during the integration process 
    csid: session_id, // Your own application session id
    uid: response.data.username, //User identifier must be unique and consistent.
    baseURL: constants.clientBaseURL // Provided during integration process
};
const ironvest = new Ironvest(options);

Examples of IronVest Class Methods Usage

To help illustrate how to use Ironvestclass, the following common use case is illustrated:

• Updating a session

• Starting biometric enrollment

• Starting a biometric session to protection of a form

• Finishing a biometric session

Updating a session

setCsid()

• Update client session ID: This function can be used to the ID on a class that was initiated without CSID (because it was unknown at the time of initialization) or to start a new session for the same or a different user. Note that this function should be called any time the csid is updated

ironvest.setCsid(<csid>);

setUid()

• Update User ID: This function can be used to the ID on a class that was initiated without UID (because it was unknown at the time of initialization) or to start a new session for the same or a different user. Note that this function should be called any time the uid is updated

ironvest.setUid(<uid>);

Starting biometric enrollment

Note that this method should be used only if active enrollment is configured

startEnrollment()

• Start biometric enrollment: To enroll a new user for biometrics. You need to specify the element id of the DOM element where the selfie image should be presented during the enrollment phase.

ironvest.startEnrollment(<mount-camera-element-id>, function () {
    // Success callback
}, function () {
    // Error Callback
})

Starting a biometric session to protection of a form

If passive enrollment is configured, this method will trigger passive enrollemnt for users who are not yet enrolled.

startBiometricSession()

Starts biometric at a protected form. This call triggers opening of a front camera to take selfie images along with screenshots for the entire period of the biometric session.

Call startBiometricSession to start the biometric session and call stopBiometric at the end to finish biometric session. Not calling stopBiometric at the end of the biometric session will result in camera remaining open and continuous capture of the user selfie images.

It's required to specify <mount-camera-element-id> parameter with the ID of the element where the camera preview should be placed in the background. This element id also designates the area where the screenshots will be collected from. If you wish to take screenshots of the entire screen set the option of captureFullScreenScreenshot to true (supported starting version 2024-11-1).

There is an option to show Virtual Avatar animation instead of camera preview (supported starting version 2024-11-1).

// Optional Parameters
const options = {
    "className": String, // optional class to append to the canvas element. Default AuthenticAction-canvas
    "width": Integer, // Width in pixels. If supplied will override all default values
    "height": Integer, // Height in pixels. If supploed will override all default values
    "opacity": Float, // Opacity. If provided will override default value of 0.3
    "frequency": Integer, // Depricated, to be removed in the next version. Please use other means to configure frame capture frequency such as actionID (was: Number of milliseconds between each frame sent to server. Dafault 5000)
    "actionID": String, // Action identifier to designate action dedicated settings, like the frequency of biometric frame capturing. Supported from version 2024-05-1 and above
    "useVirtualAvatar": Boolean, // If true, replaces the live camera stream with a virtual avatar. This feature is supported starting from version 2024-11-1 and above.
    "captureFullScreenScreenshot": Boolean, // Default False, If true, the SDK will capture a full-screen screenshot instead of just the mounted camera element. Supported starting from version 2024-11-1 and above.
}
ironvest.startBiometricSession(<mount-camera-element-id>, options)

Finishing a biometric session

stopBiometric()

• Stop biometrics at protected form: Trigger the stopBiometric function once the protected action is complete and you want to close the biometric capture and display.

ironvest.stopBiometric();

Reference: class Ironvest

Represents an AutenticAction.

Constructor

new Ironvest(options)

Initiate the AuthenticAction.

Constructor parameters:

Parameters example:

const options = {
    cid: constants.clientId, //  Provided at the integration process 
    csid: session_id, // Your own application session id
    uid: response.data.username, //User identifier must be unique and consistent.
    baseURL: constants.clientBaseURL // Provided during integration process
};

Class methods

(async) updateSession(uid)

Set CSID and UID. Can be used to start a new session, i.e. create a new scope for the data capture.

Parameters:

Name	Type	Description
csid	string	Customer Session ID. This parameter is required. If the value is identical to the one previously set, the data will continue being collected for the same context
uid	string	<Optional> User identifier must be unique and consistent. If skipped a UID that was previously set will remain in effect. If UID was not previously set, the new value will be applied for the entire session context.

startBiometricSession(elementId) → {void}

Initiates biometric session. Other AutheticAction factors are collected throughout the entire session lifetime, however biometric data requires explicit initialization that is triggered by calling this method.

Parameters:

Name	Type	Description
elementId	string	ID of the DOM element where camera feed should be mounted for presenting the selfie image to the user. If skipped, the camera feed will be captured but the selfie image will not be presented on the screen.

stopBiometric() → {void}

Finishes biometric session. Closes the camera and stops biometric capture.

Parameters:

None.

requestPermission(permissionName) → {Promise}

Supported from version 2024-06-1 and above

Request permission for a specified resource.

Parameters:

Name	Type	Description
permissionName	string	The name of the permission requested. Currently only 'camera' is supported

Returns:

Type	Description
Promise<string>	A promise that resolves to the result of the permission request: 'granted' if the permission has been granted 'denied' if the permission has been denied.

Throws:

Type	Description
Error	Throws an error if the permission request method is not implemented for the specified permissionName or another error occurred

getPermissionsStatus() → {Promise}

Supported from version 2024-06-1 and above

Check permission status of a specified resource.

Parameters:

None.

Returns:

Type	Description
Promise<Object>	A promise that resolves to an object containing the status of the used permissions. For each permission name (e.g. 'camera'): 'granted' if the permission has been granted 'denied' if the permission has been denied 'prompt' if the user has not yet been asked for the permission 'unknown' if an error occurred while checking the permission status

Troubleshooting

The SDK generates logs throughout its execution. These logs are useful to pinpointing different usage and integration issues and can be found in the browser's debug console. Normally it will only output warning and error messages. If you wish to see verbose logs you should specify debug: true option in the Ironvest class initialization.

const options = {
    cid: constants.clientId,
    csid: session_id,
    uid: response.data.username,
    baseURL: constants.clientBaseURL,
    debug: true // enable verbose logging
};
const ironvest = new Ironvest(options);

Reviewing the Network section was also proved to be useful when troubleshooting issues.