# JavaScript Programming

## Project Setup

<figure><img src="/files/jDK9kNzDY1JZqhky6C6P" alt=""><figcaption></figcaption></figure>

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.&#x20;

### **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.

```html
<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. &#x20;

### **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.&#x20;

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](/ironvest-authenticaction-developer-documentation/authenticaction-client-sdk/components-and-considerations.md#_toc148556249) 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](/ironvest-authenticaction-developer-documentation/authenticaction-client-sdk/components-and-considerations.md#_toc148556250) section.

For more information about the options, see the [Components and Considerations](/ironvest-authenticaction-developer-documentation/authenticaction-client-sdk/components-and-considerations.md) section. For more information about what data is being collected, see the [The AuthenticAction Data](/ironvest-authenticaction-developer-documentation/service-components/the-authenticaction-data.md) section.

```javascript
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

```javascript
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

```javascript
ironvest.setUid(<uid>);
```

### Starting biometric enrollment

{% hint style="info" %}
Note that this method should be used only if active enrollment is configured
{% endhint %}

### 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.

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

### Starting a biometric session to protection of a form

{% hint style="info" %}
If passive enrollment is configured, this method will trigger passive enrollemnt for users who are not yet enrolled.
{% endhint %}

### 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).&#x20;

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

```javascript
// 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.

```javascript
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 | <p>Customer Session ID. This parameter is required.<br>If the value is identical to the one previously set, the data will continue being collected for the same context</p>                                                       |
| `uid` | string | <p>\<Optional> User identifier must be unique and consistent. If skipped a UID that was previously set will remain in effect.<br>If UID was not previously set, the new value will be applied for the entire session context.</p> |

#### **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.&#x20;

*Parameters:*

<table><thead><tr><th width="354.3333333333333">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>elementId</td><td>string</td><td>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.</td></tr></tbody></table>

#### **stopBiometric() → {void}**

Finishes biometric session. Closes the camera and stops biometric capture.&#x20;

*Parameter&#x73;**:***

None.

#### requestPermissio&#x6E;**(**&#x70;ermissionNam&#x65;**) → {**&#x50;romis&#x65;**}**

{% hint style="info" %}
Supported from version 2024-06-1 and above
{% endhint %}

Request permission for a specified resource.

*Parameters:*

<table><thead><tr><th width="209.33333333333331">Name</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td><h4>permissionName</h4></td><td>string</td><td>The name of the permission requested. Currently only 'camera' is supported</td></tr></tbody></table>

*Returns:*

<table><thead><tr><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>Promise&#x3C;string></td><td><p>A promise that resolves to the result of the permission request:</p><ul><li>'granted' if the permission has been granted</li><li>'denied' if the permission has been denied.</li></ul></td></tr></tbody></table>

*Throws:*

<table><thead><tr><th width="146">Type</th><th>Description</th></tr></thead><tbody><tr><td>Error</td><td>Throws an error if the permission request method is not implemented for the specified permissionName or another error occurred</td></tr></tbody></table>

#### getPermissionsStatu&#x73;**() → {**&#x50;romis&#x65;**}**

{% hint style="info" %}
Supported from version 2024-06-1 and above
{% endhint %}

Check permission status of a specified resource.

*Parameters:*

None.

*Returns:*

<table><thead><tr><th width="206">Type</th><th>Description</th></tr></thead><tbody><tr><td>Promise&#x3C;Object></td><td><p>A promise that resolves to an object containing the status of the used permissions. For each permission name (e.g. 'camera'):</p><ul><li>'granted' if the permission has been granted</li><li>'denied' if the permission has been denied</li><li>'prompt' if the user has not yet been asked for the permission</li><li>'unknown' if an error occurred while checking the permission status</li></ul></td></tr></tbody></table>

## 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.&#x20;

```javascript
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docsjs.ironvest.com/ironvest-authenticaction-developer-documentation/authenticaction-client-sdk/javascript-programming.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.