Versão depreciada

Esta página existe apenas para clientes que ainda integram a SDK localmente via pnpm/npm (arquivo .tgz). Novas integrações devem seguir a documentação principal via CDN.

A partir da versão 2.5.0, a CDN passou a exigir o parâmetro ?v=VERSAO e versões anteriores não são mais resolvidas pelo bootstrap padrão. Se você está nesse cenário, mantenha-se nesta página até concluir a migração.

Integração Fortface SDK Web no seu web app

Instalação

Download

Você deverá fazer o download do arquivo .tgz de instalação da SDK no link a seguir: fortface-sdk-v2.5.0.tgz.

⚠️ Para facilitar o desenvolvimento com o uso de ferramentas do desenvolvdor use a versão debug mode: fortface-sdk-v2.5.0-debug-mode.tgz Não usar em seu web app de produção. Nossa SDK não permite o uso dessas ferramentas ⚠️

1. Adicionar o arquivo ao seu projeto

Exemplo:

seu_projeto/fortface-sdk-v2.5.0.tgz

HTML + Vanilla Javascript
Gerenciador de pacotes

Faça a descompressão do arquivo .tgz
Copiar a pasta package/dist/fortface-sdk para sua pasta de assets ou vendor
Exemplo: seu_projeto/vendor/fortface-sdk
Na tag head do seu arquivo, faça a importação do 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 seu gerenciador de pacotes para instalar o SDK:

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

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

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

Requisito de Segurança para Criptografia

Para garantir a segurança, o SDK requer que o ambiente em que está sendo executado suporte criptografia HTTPS, exceto em ambientes de desenvolvimento (localhost ou 127.0.0.1). Caso contrário, o SDK não será inicializado e o erro FortfaceError.FORTFACE_INSECURE_PROTOCOL será lançado.

Pré-inicialização

Antes de iniciar o processo de captura, é necessário estabelecer a integridade do dispositivo para garantir uma comunicação segura com a API Fortface. Sendo assim, é preciso:

Importar nossa SDK no seu web app;
Iniciar FortfaceSdk;
Obter deviceRequestInfo.

Estabelecer a integridade do dispositivo (instalação local)

Nosso SDK é construído como um Web Component. Isso significa que, antes de utilizar qualquer método exposto pelo SDK, é necessário registrar as definições nativas do navegador chamando a função defineCustomElements(). Esse registro permite que o navegador reconheça e inicialize corretamente os componentes. Após executado, é importante garantir que o componente já foi registrado antes de interagir com ele — por exemplo, chamando métodos públicos como start() ou startSession(). Para isso, recomenda-se utilizar a API nativa customElements.whenDefined('fortface-sdk') juntamente com await, garantindo que o elemento esteja totalmente pronto e disponível antes de continuar a execução.

Além disso, em aplicações que utilizam Server-Side Rendering (SSR), é necessário se atentar para que o registro e a utilização dos componentes do Fortface SDK não sejam executados no servidor, onde o objeto window e o customElements não estão disponíveis.

Inicie a SDK e obtenha o deviceRequestInfo.

HTML + Vanilla Javascript
React
Angular
Vue.js

<!DOCTYPE html>
<html>
   <head>
      <title>Exemplo com 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'; // para typescript

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

declare global { // para typescript e versões do React anteriores a 19
  namespace JSX {
    interface IntrinsicElements extends FortfaceJSX.IntrinsicElements {
      'fortface-sdk': FortfaceJSX.FortfaceSdk &
        React.DetailedHTMLProps<React.HTMLAttributes<HTMLFortfaceSdkElement>, HTMLFortfaceSdkElement>;
    }
  }
}

declare module 'react' { // para typescript e versões do 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({
  ...
  // Configuração do schemas no app.component.ts a partir da versão 17
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent {
    ...
    @ViewChild('fortfaceSdk') fortfaceSdkRef!: ElementRef<FortfaceSdk>;
    ...
    async startFortfaceSdk() {
      const deviceRequestInfo = await this.fortfaceSdkRef.nativeElement.start();
    }
}

Configuração do schemas no app.module.ts (até versão 16)

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

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

Configuração adicional na versão 14

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

// main.ts (mesmo arquivo do 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>

Remoção da função applyPolyfills

A partir da versão 2.3.0, a função applyPolyfills não é mais disponibilizada. Com isso, não há necessidade dessa configuração que será feito de forma automática. Caso você esteja utilizando uma versão anterior a 2.3.0, atualize e siga os exemplos anteriores.

Com deviceRequestInfo em mãos, é possível realizar handshake entre seu back-end e API Fortface.

Permissões de Câmera

Nosso SDK gerencia automaticamente a solicitação de permissões de câmera. No entanto, caso sua aplicação precise solicitar essas permissões antes de chamar o método start do SDK, é essencial interromper qualquer stream de câmera ativo antes da pré-inicialização do SDK. Isso garante o funcionamento correto da abertura da câmera para a captura. Por exemplo:

// Solicita permissão de câmera antes da inicialização do SDK
const tracks = await navigator.mediaDevices.getUserMedia({ video: true });

// Antes de pré-inicializar o SDK, certifique-se de interromper qualquer stream de câmera ativo
tracks.getTracks().forEach((track) => track.stop());

// Agora é seguro pré-inicializar o SDK
fortfaceSdk.start();

Versionamento

Para saber qual versão da nossa SDK está sendo utilizada, basta chamar a função getVersion(). Exemplo:

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();

Demais seções

Para o que se segue após a pré-inicialização, o comportamento da SDK é idêntico à integração via CDN. Consulte na página principal:

Instalação​

Download​

1. Adicionar o arquivo ao seu projeto​

Exemplo:​

Pré-inicialização​

Estabelecer a integridade do dispositivo (instalação local)​

Configuração do schemas no app.module.ts (até versão 16)​

Configuração adicional na versão 14​

Permissões de Câmera​

Versionamento​

Demais seções​