Fortface SDK Web Integration in Your Web App

How does it work?​

Our SDK is designed to perform the capture or upload of the photo that will be sent to our Fortface API. It is independent of your app’s flow and can be initialized at any time within your app.

Our SDK does not communicate directly with the Fortface API; see the communication flow below:

Communication Flow

Below are the instructions for integrating our SDK.

CDN Integration​

Integration via package manager (legacy)

If you still integrate the SDK locally via pnpm/npm (.tgz file), see the deprecated version of this page. The recommended path for new integrations is via CDN.

The endpoint https://cdn-loader.isface.live/sdk.js?t=YOUR_CLIENT_ID&v=VERSION is the official bootstrap for the Fortface Web SDK.

When this script is loaded in the browser:

  1. The clientId (Gallery Id) sent in the t parameter is validated.
  2. The version sent in the v parameter is validated and resolved.
  3. The corresponding bundle is loaded from the Fortface CDN.
  4. The global FortfaceSDK object becomes available for initialization via FortfaceSDK.load().

In this approach:

  • There is no need to install the SDK as a package (npm, yarn, pnpm).
Parameter values
  • For the clientId value in the t parameter, send your Gallery Id.
  • For the version value in the v parameter, send the version compatible with your application.
<!DOCTYPE html>
<html>
  <head>
    <title>Example with Fortface SDK</title>
    <script src="https://cdn-loader.isface.live/sdk.js?t=YOUR_CLIENT_ID&v=VERSION"></script>
  </head>
  <body>
    <fortface-sdk id="fortfaceSdk"></fortface-sdk>

    <script>
      async function fortfaceSdkInit() {
        await FortfaceSDK.load();
        const fortfaceSdk = document.querySelector('#fortfaceSdk');

        // Document capture
        const deviceRequestInfo = await fortfaceSdk.startDoc();

        // Document upload
        // const deviceRequestInfo = await fortfaceSdk.startDocUpload();
      }

      document.addEventListener('DOMContentLoaded', function () {
        void fortfaceSdkInit();
      });
    </script>
  </body>
</html>

Alternative option: programmatic loading via JavaScript​

Use this option when it is not possible to declare the <script> tag directly in the application's base HTML.

<div id="fortface-root"></div>

<script>
  async function mountFortfaceSdk(clientId, version, containerSelector) {
    await new Promise(function (resolve, reject) {
      const script = document.createElement('script');
      script.src = 'https://cdn-loader.isface.live/sdk.js?t=' + encodeURIComponent(clientId) + '&v=' + encodeURIComponent(version);
      script.async = true;
      script.onload = resolve;
      script.onerror = function () {
        reject(new Error('Failed to load the Fortface SDK bootstrap'));
      };
      document.head.appendChild(script);
    });

    await FortfaceSDK.load();

    const element = document.createElement('fortface-sdk');
    document.querySelector(containerSelector).appendChild(element);

    return element;
  }

  mountFortfaceSdk('YOUR_CLIENT_ID', 'VERSION', '#fortface-root').then(async function (fortfaceSdk) {
    const deviceRequestInfo = await fortfaceSdk.startDoc();
  });
</script>
Security Requirement for Encryption

To ensure security, the SDK requires that the execution environment supports HTTPS encryption, except in development environments (localhost or 127.0.0.1). Otherwise, the SDK will not initialize and the error FortfaceError.FORTFACE_INSECURE_PROTOCOL will be thrown.

Debug version (staging / homologation)​

In staging environments or for debugging purposes, the Fortface Web SDK provides a special variant accessible through the /sdk.debug.js endpoint. The t and v parameters remain the same.

<!-- Production -->
<script src="https://cdn-loader.isface.live/sdk.js?t=YOUR_CLIENT_ID&v=VERSION"></script>

<!-- Debug / Staging -->
<script src="https://cdn-loader.isface.live/sdk.debug.js?t=YOUR_CLIENT_ID&v=VERSION"></script>

For programmatic loading, replace the URL equivalently:

const script = document.createElement('script');
script.src =
  'https://cdn-loader.isface.live/sdk.debug.js?t=' +
  encodeURIComponent(clientId) +
  '&v=' +
  encodeURIComponent(version);

When using the debug endpoint:

  • The Fortface CDN serves the debug bundle for the requested version (e.g. 2.5.0-debug-mode).
  • The CDN response includes the x-sdk-mode: debug header.
  • The version effectively loaded is indicated in the x-sdk-version header.
Debug mode access

If you receive a 403 error when requesting the /sdk.debug.js endpoint, please contact the Fortface team to request debug mode access for your environment.

Pre-initialization​

Before starting the capture process, you must establish the device’s integrity to guarantee secure communication with the Fortface API. Therefore, you must:

  1. Load the official bootstrap (/sdk.js?t=YOUR_CLIENT_ID&v=VERSION);
  2. Initialize the SDK via FortfaceSDK.load();
  3. Obtain deviceRequestInfo from the <fortface-sdk> element.

Establish Device Integrity​

Our SDK is built as a Web Component. In the CDN distribution, the component registration is done during FortfaceSDK.load(). Therefore, before using methods like startDoc(), startDocUpload(), startSessionDoc() and startSessionDocUpload(), wait for this method to resolve.

In applications with Server-Side Rendering (SSR), execute this logic only in the browser.

Initialize the SDK and obtain the deviceRequestInfo.

async function fortfaceSdkInit() {
  await FortfaceSDK.load();

  const fortfaceSdk = document.querySelector('fortface-sdk');

  // For document capture
  const deviceRequestInfo = await fortfaceSdk.startDoc();

  // For document upload
  // const deviceRequestInfo = await fortfaceSdk.startDocUpload();
}
Removal of the applyPolyfills function

From version 2.3.0, the applyPolyfills function is no longer available. Therefore, there is no need for this configuration, which will be done automatically. If you are using a version prior to 2.3.0, update and follow the previous examples.

With deviceRequestInfo in hand, you can perform a handshake between your backend and the Fortface API.

The handshake is an important security measure to establish reliable communication between your backend and the Fortface API, allowing verification of device authenticity, sharing of sensitive information (encryption keys and sessions), and establishing a secure data exchange channel.

Upon a successful handshake, you are assured that the device is secure and your app has the necessary information to proceed.

Camera Permissions​

Our SDK automatically handles the camera permission request. However, if your application needs to request these permissions before calling the SDK’s startDoc method, it is essential to stop any active camera stream before the SDK’s pre-initialization. This ensures that the camera opens correctly for capture. For example:

// Request camera permission before initializing the SDK
const tracks = await navigator.mediaDevices.getUserMedia({ video: true });

// Before pre-initializing the SDK, ensure you stop any active camera stream
tracks.getTracks().forEach((track) => track.stop());

// Now it is safe to pre-initialize the SDK
fortfaceSdk.startDoc();

Capture and Upload of Documents​

File Size Limit

The maximum file size (PDF/Image) for upload is 4MB. Larger files will be rejected with error code fileSizeTooBig.

Once device integrity is established, let’s see how to start the session.

Session Initialization​

After the handshake, your backend provides the necessary information for your frontend to initialize the session in the SDK using the startSessionDoc function for document capture, or the startSessionDocUpload function for document upload.

This function accepts 3 parameters:

  1. fortfaceFinishSession (IFortfaceFinishSession): the callback function to be called after capture;
  2. sessionId (string): the session identifier received during the handshake;
  3. sessionKey (string): the session key received during the handshake;

Creating a Callback​

The callback function fortfaceFinishSession will receive an object with the performed action (FortfaceActionEnum) and the result of the action (IFortfaceData). This allows you to define the flow to be executed after capture:

function fortfaceFinishSession(fortfaceSessionResult: SessionEngineResult) {
  const { action, data, sessionDetails } = fortfaceSessionResult;

  switch (action) {
    case 'capture':
      handleResult(data, sessionDetails);
      break;
    case 'cancel':
      handleCancel(data, sessionDetails);
      break;
    case 'timeout':
      handleTimeout(data, sessionDetails);
      break;
    case 'timeout_ready':
      handleTimeoutReady(data, sessionDetails);
      break;
    case 'error':
      handleError(data, sessionDetails);
      break;
    default:
      break;
  }
}

function handleResult(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const imgPreview = fortfaceData.imgPreview; // Available only in the document capture functionality
  const metrics = sessionDetails.metrics;
  // Here the flow ends and these are the data to be sent to the Fortface API
}

function handleCancel(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Here the user canceled the capture (our the upload) and you should send the returned data to the Fortface API and proceed with your cancellation flow
}

function handleTimeout(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Here the capture was canceled because the time ran out. You should send the returned data to the Fortface API and proceed with the timeout flow
}

function handleTimeoutReady(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Here the capture was canceled because the SDK’s ready state timeout was reached.
  // You should send the returned data to the Fortface API and proceed with the ready timeout flow
}

function handleError(data: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const { errorCode, metrics } = sessionDetails;
  // An error occurred and you should proceed with your error flow
}

ATTENTION!!​

  • The flow is executed for each "side" of the document, i.e., front and back. Each must complete the full flow, going through startDoc (or startDocUpload), handshake, and startSessionDoc (or startSessionDocUpload).

Calling the startSessionDoc / startSessionDocUpload Function​

const sessionId = 'response from the Fortface API';
const sessionKey = 'response from the Fortface API';
fortfaceSdk.startSessionDoc(fortfaceFinishSession, sessionId, sessionKey); // For document capture
fortfaceSdk.startSessionDocUpload(fortfaceFinishSession, sessionId, sessionKey); // For document upload

Mock data for example:

sessionId = "nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2k"

sessionKey = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2k+o81Oiti4TDezZYD8Q\nzj2RjO5f/YQHGmC1v7CWC4AJpD9+FOXBBO1pImaSg1gb8kOobRFGWbVdiHm35+PF\nTJceH31r+jKnvfc1TshsQVGtYLm7x5E/GFcjpGx9LdSxiXC6cHdCJf3o02/lytBa\nu8NCoH9FpPjyKrdGdSRb2haviAuEV4N1UBd5uZIsacVqZj52i1z+I94gLVKBZ/UV\npaxjLPWWngmaxbyKE0sEbt9JGleiCb2P1kZA9sU4L4Po7WBNk0+QOsvW9QjvS1+6\ntcZwwIDll2LyUceiFgxF6GkuFcHlBZDDtzymDDC2IYrf9/FNBOPeV1JHXON8T6DY\nAwIDAQAB\n-----END PUBLIC KEY-----\n"

Handling the sessionKey

The string that represents the sessionKey contains special characters (such as the line break \n) that must be preserved exactly as received from the Fortface API. Be careful with any accidental manipulation that may occur in:

  • Form inputs
  • Logs and monitoring systems
  • String processing in your backend
  • Transfers between services
  • Database storage

Any change to these characters may cause the key validation to fail. Make sure the key is passed to the SDK exactly as received from the Fortface API.

Development facilitation

For local frontend development only, you may reuse the same valid sessionKey as a mock as many times as necessary. The single-use restriction applies only in the context of backend development, when the Fortface API validates the key.

Versioning​

To know which version of our SDK is being used, simply call the function getVersion(). Example:

const version = await fortfaceSdk.getVersion();

Error handling​

During use of the Web SDK, errors can occur at different stages of execution. These errors must be handled according to when they happen. There are two main scenarios:

  1. Errors during execution of the startDoc or startDocUpload method;
  2. Errors during document capture, after executing the startSessionDoc or startSessionDocUpload method.

Errors during execution of the startDoc or startDocUpload method​

Errors thrown during execution of the startDoc or startDocUpload method are propagated as exceptions, because at this stage there is no access to the fortfaceFinishSession callback. This means that it is not possible to return the FortfaceActionEnum.ERROR action directly to the application.

Possible errors are:

  • FORTFACE_INSECURE_PROTOCOL: The SDK is being executed in an insecure environment (for example, via HTTP).
  • FORTFACE_GENERATE_DEVICE_REQUEST_INFO_ERROR: Failure to generate the deviceRequestInfo, necessary for the handshake.
  • FORTFACE_INTERNAL_SETUP_ERROR: Failure to initialize mandatory internal resources to start the session.
  • FORTFACE_UNEXPECTED_START_ERROR: Unexpected error occurred during execution of the start method.

To handle these errors, you must use the try/catch block to capture the exception:

try {
  await fortfaceSdk.start();
} catch (error) {
  const errorName = error.name;
  switch (errorName) {
    case 'FORTFACE_INSECURE_PROTOCOL':
      // Handle insecure environment error
      break;
    case 'FORTFACE_GENERATE_DEVICE_REQUEST_INFO_ERROR':
      // Handle deviceRequestInfo generation error
      break;
    case 'FORTFACE_INTERNAL_SETUP_ERROR':
      // Handle internal resources initialization error
      break;
    case 'FORTFACE_UNEXPECTED_START_ERROR':
      // Handle unexpected error
      break;
  }
}

Errors during document capture (startSessionDoc or startSessionDocUpload):​

After executing the startSessionDoc or startSessionDocUpload method, any errors are returned at runtime through the fortfaceFinishSession callback. In these cases, the returned action will be FortfaceActionEnum.ERROR, accompanied by the respective errorCode.

Possible errorCode values:

  • notInitialized: The startSessionDoc or startSessionDocUpload method was called before the startDoc or startDocUpload (respectively) method was executed.
  • invalidSessionKey: The provided sessionKey is invalid.
  • detectorError: Failure in facial biometric points detection; it was not possible to locate valid points in sequence.
  • debugError: Attempt to inspect the SDK in production mode with browser developer tools.
  • cameraDisconnected: The camera was disconnected during capture and the showPreviewModalIfError customization (to choose another camera) is disabled.
  • cameraUnreliable: Cameras were detected, but none could be used.
  • noCompatibleVideoDevice: No compatible camera was found.
  • cameraPermissionDenied: The user denied access to the camera.
  • cameraUnavailable: The camera is unavailable (blocked by another resource or system).
  • cameraAccessPolicyRestricted: Access denied by security policies, usually when executing the SDK inside an iframe.
  • cameraAccessUnexpectedError: An unexpected error occurred while accessing the camera.
  • browserUnsupported: The browser is not compatible with facial biometrics (see support section).
  • browserValidationUnexpectedError: An unexpected error occurred while validating the browser.
  • fileCorrupted: Exclusive to the document upload feature. Occurs when the file is corrupted.
  • fileInvalid: Exclusive to the document upload feature. Occurs when the file is invalid, such as a password-protected PDF or without pages.
  • fileSizeTooBig: Exclusive to the document upload feature. Occurs when the file exceeds the allowed limit of 5MB.

Example of handling via callback:

function fortfaceFinishSession(fortfaceSessionResult: SessionEngineResult) {
  const { action, sessionDetails } = fortfaceSessionResult;

  switch (action) {
    case 'error':
      const { errorCode } = sessionDetails;

      if (errorCode === 'cameraPermissionDenied') {
        // Inform the user to allow access to the camera
      }

      // Add other treatments as needed
      break;
  }
}
  • Keep a log of captured errors to facilitate diagnosis and support.
  • Guide the user clearly when errors related to the browser, camera, or permissions occur.
  • Regularly check the SDK release notes for new error codes or API changes.

SDK Compatibility with Production Builds​

There are some scenarios in which applications using the Fortface SDK run without issues in development, yet encounter failures only in production, after the build or deployment. In such situations — for example, when the camera does not open in production — it is important to consider how the application's build process may be interfering with the SDK's execution.

When using CDN integration, the SDK is not bundled by your application's build process.

To avoid failures in production:

  1. Ensure the script https://cdn-loader.isface.live/sdk.js?t=YOUR_CLIENT_ID&v=VERSION is present in the final HTML of the application, or is injected into the browser before calling FortfaceSDK.load().
  2. Execute FortfaceSDK.load() only on the client-side.
  3. In SSR applications, protect the flow to prevent execution on the server.
  4. Review CSP policies to allow cdn-loader.isface.live and cdn.isface.live in script-src.

Typescript​

1. FortfaceSdk​

interface FortfaceSdk {
  getVersion: () => Promise<string>;
  setCustomizer: ({ camera, instructions }: IFortfaceCustomizer) => Promise<void>;
  startDoc: () => Promise<string>;
  startDocUpload: () => Promise<string>;
  startSessionDoc: (
    fortfaceFinishSession: IFortfaceFinishSession,
    sessionId: string,
    sessionKey: string
  ) => Promise<void>;
  startSessionDocUpload: (
    fortfaceFinishSession: IFortfaceFinishSession,
    sessionId: string,
    sessionKey: string
  ) => Promise<void>;
}

2. IFortfaceFinishSession​

interface IFortfaceFinishSession {
  (fortfaceSessionResult: IFortfaceSessionResult): void;
}

3. IFortfaceSessionResult​

interface IFortfaceSessionResult {
  action: FortfaceActionEnum;
  data: IFortfaceData;
  sessionDetails?: {
    errorCode?: FortfaceSessionErrorCode;
  };
}

4. FortfaceActionEnum​

enum FortfaceActionEnum {
  ABORT = 'abort',
  CANCEL = 'cancel',
  CAPTURE = 'capture',
  TIMEOUT = 'timeout',
  TIMEOUT_READY = 'timeout_ready',
  DOCUMENT = 'document',
  ERROR = 'error',
}

5. IFortfaceData​

interface IFortfaceData {
  encryptData?: {
    data: string;
    imgData?: string;
    key: string;
  };
  imgPreview?: string; // Available only in the document capture functionality
}

6. FortfaceSessionErrorCode​

enum FortfaceSessionErrorCode {
  detectorError = 'detectorError',
  debugError = 'debugError',
  cameraUnreliable = 'cameraUnreliable',
  fileCorrupted = 'fileCorrupted',
  fileInvalid = 'fileInvalid',
  fileSizeTooBig = 'fileSizeTooBig',
  invalidSessionKey = 'invalidSessionKey',
  cameraDisconnected = 'cameraDisconnected',
  noCompatibleVideoDevice = 'noCompatibleVideoDevice',
  cameraPermissionDenied = 'cameraPermissionDenied',
  cameraUnavailable = 'cameraUnavailable',
  cameraAccessPolicyRestricted = 'cameraAccessPolicyRestricted',
  cameraAccessUnexpectedError = 'cameraAccessUnexpectedError',
  browserUnsupported = 'browserUnsupported',
  browserValidationUnexpectedError = 'browserValidationUnexpectedError',
  notInitialized = 'notInitialized',
}

7. IFortfaceCustomizer​

interface IFortfaceCustomizer {
  base?: IFortfaceBase;
  cameraDoc?: IFortfaceCameraDoc;
  docUpload?: IFortfaceDocUpload;
}

8. IFortfaceBase​

export interface IFortfaceBase {
  timeout?: number;
}

9. IFortfaceCameraDoc​

interface IFortfaceCameraDoc {
  timeout?: number;
  startMessage?: string;
  captureReviewMessage?: string;
  cancelButtonImage?: string;
  showCancelButton?: boolean;
  waitCameraDescription?: string[];
  captureDocButtonMessage?: string;
  captureDocButtonColor?: string;
  captureDocButtonTextColor?: string;
  captureDocButtonPressedColor?: string;
  retryCaptureButtonMessage?: string;
  retryCaptureButtonColor?: string;
  retryCaptureButtonTextColor?: string;
  retryCaptureButtonPressedColor?: string;
  sendCaptureButtonMessage?: string;
  sendCaptureButtonColor?: string;
  sendCaptureButtonTextColor?: string;
  sendCaptureButtonPressedColor?: string;
  fontFamily?: string;
}

10. IFortfaceDocUpload​

interface IFortfaceDocUpload {
  initialBottomSheet?: {
    fontFamily?: string;
    textColor?: string;
    titleMessage?: string;
    openGalleryButtonMessage?: string;
    openGalleryButtonBg?: string;
    openGalleryButtonTextColor?: string;
    openGalleryButtonPressedColor?: string;
    cancelButtonMessage?: string;
    cancelButtonTextColor?: string;
    cancelButtonPressedColor?: string;
  };
  reviewScreen?: {
    fontFamily?: string;
    textColor?: string;
    titleMessage?: string;
    descriptionMessage?: string;
    cancelButtonImage?: string;
    showCancelButton?: boolean;
    retryButtonMessage?: string;
    retryButtonTextColor?: string;
    retryButtonPressedColor?: string;
    confirmButtonMessage?: string;
    confirmButtonColor?: string;
    confirmButtonTextColor?: string;
    confirmButtonPressedColor?: string;
  };
  pdfPreviewUnavailable?: {
    titleMessage?: string;
    descriptionMessage?: string;
  };
}

Error, Cancellation, Timeout, and Timeout_Ready Callback​

When an attempt to capture the user's face is not completed successfully - for example, when the user cancels the capture, when the capture does not occur within the specified time (only for document capture), or when the identification engine's ready timeout is reached (only for document capture) - it is important that this event be sent to your backend so that accurate metrics for capture success or failures can be obtained.

The SessionEngineResult received in the finishedSessionEngine function is an object with three properties: data, action (the action performed by the SDK), and may contain sessionDetails in case of an error.

As mentioned earlier in the Capture section, the data contains encrypted information and can be converted to JSON. However, unlike a successful capture, in this scenario after JSON conversion we will only have the following fields:

{
    key: String,
    data: String,
}

Reminder: The keys “key” and “data” are generated by the SDK, sent to your backend, and then to the Fortface API.​

Implementation Example​

  1. The SDK detects that the capture was canceled.
  2. An encrypted object is created.
  3. The SDK terminates and sends the generated payload along with the performed action.
  4. In the integrating app, within the startSession function the first parameter is a callback function that returns the SDK result.
// Callback function handling your statuses

const handleSessionCallback = async (fortfaceSessionResult: IFortfaceSessionResult) => {
  switch (fortfaceSessionResult.action) {
    case 'error':
      const errorCode = fortfaceSessionResult.sessionDetails?.errorCode;
      handleMetrics(fortfaceSessionResult.data);
      break;
    case 'cancel':
      handleMetrics(fortfaceSessionResult.data);
      break;
    case 'timeout':
      handleMetrics(fortfaceSessionResult.data);
      break;
    case 'timeout_ready':
      handleMetrics(fortfaceSessionResult.data);
      break;
  }
};

Support​

The minimum versions for each browser that our SDK Web supports are listed below:

Android:

  • Chrome: v112
  • Firefox: v110
  • Edge: v103
  • Samsung Internet: v11.1
  • Opera: v73

iOS:

  • Minimum iOS version for all browsers: v15.4
  • Chrome: v112
  • Firefox: v110
  • Edge: v103
  • Safari: v15.4
  • Opera: v73

Desktop:

  • Chrome: v103
  • Firefox: v103
  • Edge: v103
  • Safari: v15.4
  • Opera: v86

Summary​

  1. Download the SDK;
  2. Installation;
  3. Capture the deviceRequestInfo;
  4. Perform the Fortface API handshake (via your backend);
  5. Create a callback function;
  6. Start the session;
  7. Receive the data (data, imgData, key);
  8. Send it to the Fortface API (via your backend);
  9. Receive the response from the Fortface API and proceed with your business logic.
Last updated on by Dionnatas Santa Fé Filho