Deprecated version

This page exists only for clients who still integrate the SDK locally via pnpm/npm (.tgz file). New integrations should follow the main documentation via CDN.

Starting from version 2.5.0, the CDN requires the ?v=VERSION parameter and previous versions are no longer resolved by the default bootstrap. If you are in this scenario, stay on this page until you complete the migration.

Fortface SDK Web Integration in Your Web App

Installation

Download

You should download the .tgz installation file for the SDK from the following link: fortface-sdk-v2.4.3.tgz.

⚠️ To facilitate development using developer tools, use the debug mode version: fortface-sdk-v2.4.3-debug-mode.tgz Do not use in your production web app. Our SDK does not allow the use of these tools ⚠️

1. Add the file to your project

Example:

your_project/fortface-sdk-v2.4.3.tgz

HTML + Vanilla Javascript
Package Manager

Uncompress the .tgz file
Copy the folder package/dist/fortface-sdk to your assets or vendor folder
Example: your_project/vendor/fortface-sdk
In the head tag of your file, import the SDK:

<head>
  <script type="module" src="/vendor/fortface-sdk/fortface-sdk.esm.js"></script>
  <script nomodule src="/vendor/fortface-sdk/fortface-sdk.js"></script>
</head>

Use your package manager to install the SDK:

yarn add file:fortface-sdk-v2.4.3.tgz

npm install ./fortface-sdk-v2.4.3.tgz --save

pnpm add ./fortface-sdk-v2.4.3.tgz

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.

Pre-initialization

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

Import our SDK into your web app;
Initialize FortfaceSdk;
Obtain deviceRequestInfo.

Establish Device Integrity (local installation)

Our SDK is built as a Web Component. This means that before you use any method exposed by the SDK, you must register the browser's native definitions by calling the defineCustomElements() function. This registration allows the browser to recognize and initialize the components correctly. After executing, it is important to ensure that the component has already been registered before interacting with it — for example, calling public methods like start() or startSession(). For this, it is recommended to use the native API customElements.whenDefined('fortface-sdk') together with await, ensuring that the element is completely ready and available before continuing execution.

Furthermore, in applications that use Server-Side Rendering (SSR), it is important to ensure that the registration and use of the Fortface SDK components are not executed on the server, where the window and customElements objects are not available.

Initialize the SDK and obtain the deviceRequestInfo.

HTML + Vanilla Javascript
React
Angular
Vue.js

<!DOCTYPE html>
<html>
   <head>
      <title>Example with Fortface SDK</title>

      <script type="module" src="/vendor/fortface-sdk/fortface-sdk.esm.js"></script>
      <script nomodule src="/vendor/fortface-sdk/fortface-sdk.js"></script>
   </head>
   <body>
      <div>
        <fortface-sdk></fortface-sdk>
      </div>
      <script>
        function fortfaceSdkInit() {
          customElements.whenDefined('fortface-sdk').then(async () => {
            const fortfaceSdk = document.querySelector("fortface-sdk");
            const deviceRequestInfo = await fortfaceSdk.start();
          });
        }
        document.addEventListener("DOMContentLoaded", function () {
          fortfaceSdkInit();
        });
      </script>
   </body>
</html>

// app.tsx
import { defineCustomElements } from 'fortface-sdk/loader';
import { JSX as FortfaceJSX } from 'fortface-sdk'; // for typescript

(async () => {
  defineCustomElements();
  await customElements.whenDefined('fortface-sdk');
})();

declare global { // for typescript and versions of React prior to 19
  namespace JSX {
    interface IntrinsicElements extends FortfaceJSX.IntrinsicElements {
      'fortface-sdk': FortfaceJSX.FortfaceSdk &
        React.DetailedHTMLProps<React.HTMLAttributes<HTMLFortfaceSdkElement>, HTMLFortfaceSdkElement>;
    }
  }
}

declare module 'react' { // for typescript and versions of React 19+
  namespace JSX {
    interface IntrinsicElements extends FortfaceJSX.IntrinsicElements {
      'fortface-sdk': FortfaceJSX.FortfaceSdk &
        React.DetailedHTMLProps<React.HTMLAttributes<HTMLFortfaceSdkElement>, HTMLFortfaceSdkElement>;
    }
  }
}

// sample-page.tsx
import { useRef } from 'react';

export default function SamplePage() {
  const fortfaceSdkRef = useRef < HTMLFortfaceSdkElement > null;

  const getDeviceRequestInfo = async () => {
    const deviceRequestInfo = await fortfaceSdkRef.current?.start();
  };

  return <fortface-sdk ref={fortfaceSdkRef} />;
}

// main.ts
...
import { defineCustomElements } from 'fortface-sdk/loader';
...

(async () => {
  defineCustomElements();
  await customElements.whenDefined('fortface-sdk');
})();

// app.component.html ...

<button (click)="startFortfaceSdk()">Start Fortface SDK</button>

<fortface-sdk #fortfaceSdk></fortface-sdk>

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild } from '@angular/core';
import { IFortfaceCustomizer, IFortfaceSessionResult, IFortfaceFinishSession } from 'fortface-sdk';


interface FortfaceSdk {
  getVersion: () => Promise<string>;
  setCustomizer: ({ camera, instructions }: IFortfaceCustomizer) => Promise<void>;
  start: () => Promise<string>;
  startSession: (fortfaceFinishSession: IFortfaceFinishSession, sessionId: string, sessionKey: string, sessionDetails?: IFortfaceSessionDetails) => Promise<void>;
}

@Component({
  ...
  // Schemas configuration in app.component.ts starting from version 17
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent {
    ...
    @ViewChild('fortfaceSdk') fortfaceSdkRef!: ElementRef<FortfaceSdk>;
    ...
    async startFortfaceSdk() {
      const deviceRequestInfo = await this.fortfaceSdkRef.nativeElement.start();
    }
}

Schemas configuration in app.module.ts (up to version 16)

// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  ...
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

Additional configuration in version 14

// tsconfig.json
{
  "lib": ["es2020", "dom", "dom.iterable", "esnext"]
}

// main.ts (same file as createApp)

...
import { defineCustomElements } from 'fortface-sdk/loader'

(async () => {
  defineCustomElements();
  await customElements.whenDefined('fortface-sdk');
})();
...

// App.vue

<script setup lang="ts">
...
import { ref, onMounted } from 'vue';
...

interface FortfaceSdk extends HTMLElement {
  getVersion: () => Promise<string>
  setCustomizer: ({ camera, instructions }: IFortfaceCustomizer) => Promise<void>
  start: () => Promise<string>
  startSession: (
    fortfaceFinishSession: IFortfaceFinishSession,
    sessionId: string,
    sessionKey: string,
    sessionDetails?: IFortfaceSessionDetails
  ) => Promise<void>
}

let fortfaceSdkRef = ref<FortfaceSdk | null>(null)

...

onMounted(() => {
  fortfaceSdkRef.value = document.getElementById('fortfaceSdk') as FortfaceSdk
})
</script>

<template>
  <main>
    ...
    <fortface-sdk id="fortfaceSdk"></fortface-sdk>
  </main>
</template>

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 back-end and the Fortface API.

Camera Permissions

Our SDK automatically handles the camera permission request. However, if your application needs to request these permissions before calling the SDK’s start 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, make sure to stop any active camera stream
tracks.getTracks().forEach((track) => track.stop());

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

Versioning

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

HTML + Vanilla Javascript
React
Angular
Vue

const version = await fortfaceSdk.getVersion();

const version = await fortfaceSdkRef.current?.getVersion();

const version = await this.fortfaceSdkRef.nativeElement.getVersion();

const version = await fortfaceSdkRef.value?.getVersion();

Other sections

For what follows after pre-initialization, the behavior of the SDK is identical to the CDN integration. See the main page:

Installation​

Download​

1. Add the file to your project​

Example:​

Pre-initialization​

Establish Device Integrity (local installation)​

Schemas configuration in app.module.ts (up to version 16)​

Additional configuration in version 14​

Camera Permissions​

Versioning​

Other sections​