🖥️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 Ironvest
class, 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
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
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.
"screenCaptureElementId": String, // The element ID used for screen capture. By default, only the mounted camera element is captured unless `captureFullScreenScreenshot` is set to true, in which case the full screen is captured.
}
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:
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:
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}
Request permission for a specified resource.
Parameters:
Returns:
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:
Error
Throws an error if the permission request method is not implemented for the specified permissionName or another error occurred
getPermissionsStatus() → {Promise}
Check permission status of a specified resource.
Parameters:
None.
Returns:
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.
Last updated