Integração Fortface SDK Web no seu web app

Como funciona?​

Nossa SDK tem como objetivo efetuar a captura da foto que será enviada para nossa API Fortface. Ela é independente do fluxo do aplicativo do app o qual irá se integrar e é inicializado a qualquer momento dentro do seu app.

Nossa SDK não comunica diretamente com a API Fortface, veja abaixo o fluxo de comunicação:

Fluxo de comunicação

Abaixo, seguem as instruções de integração do nossa SDK.

Integração via CDN​

Integração via gerenciador de pacotes (legado)

Se você ainda integra a SDK localmente via pnpm/npm (arquivo .tgz), consulte a versão depreciada desta página. O caminho recomendado para novas integrações é via CDN.

Opção recomendada: bootstrap global via CDN​

O endpoint https://cdn-loader.isface.live/sdk.js?t=SEU_CLIENT_ID&v=VERSAO é o bootstrap oficial do Fortface SDK Web.

Quando esse script é carregado no browser:

  1. O clientId (Gallery Id) enviado no parâmetro t é validado.
  2. O version (Versão) enviada no parâmetro v é validada e resolvida.
  3. O bundle correspondente é carregado da CDN Fortface.
  4. O objeto global FortfaceSDK fica disponível para inicialização via FortfaceSDK.load().

Nesta abordagem:

  • Não é necessário instalar SDK por pacote (npm, yarn, pnpm).
Valores dos parâmetros
  • Para o valor do clientId no parâmetro t envie o seu Gallery Id.
  • Para o valor do version no parâmetro v envie a versão compativel com sua aplicação.
<!DOCTYPE html>
<html>
  <head>
    <title>Exemplo com Fortface SDK</title>
    <script src="https://cdn-loader.isface.live/sdk.js?t=SEU_CLIENT_ID&v=VERSAO"></script>
  </head>
  <body>
    <fortface-sdk id="fortfaceSdk"></fortface-sdk>

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

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

Opção alternativa: carregamento programático via JavaScript​

Use esta opção quando não for possível declarar a tag <script> diretamente no HTML base da aplicação.

<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('Falha ao carregar o bootstrap do Fortface SDK'));
      };
      document.head.appendChild(script);
    });

    await FortfaceSDK.load();

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

    return element;
  }

  mountFortfaceSdk('SEU_CLIENT_ID', 'VERSAO', '#fortface-root').then(async function (fortfaceSdk) {
    const deviceRequestInfo = await fortfaceSdk.start();
  });
</script>
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.

Versão de debug (homologação)​

Em ambientes de homologação ou para fins de depuração, o Fortface SDK Web disponibiliza uma variante especial acessível pelo endpoint /sdk.debug.js. Os parâmetros t e v permanecem os mesmos.

<!-- Produção -->
<script src="https://cdn-loader.isface.live/sdk.js?t=SEU_CLIENT_ID&v=VERSAO"></script>

<!-- Debug / Homologação -->
<script src="https://cdn-loader.isface.live/sdk.debug.js?t=SEU_CLIENT_ID&v=VERSAO"></script>

Para o carregamento programático, substitua a URL de forma equivalente:

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

Ao utilizar o endpoint de debug:

  • A CDN Fortface serve o bundle de debug correspondente à versão solicitada (por exemplo, 2.5.0-debug-mode).
  • A resposta da CDN inclui o header x-sdk-mode: debug.
  • A versão efetivamente carregada é indicada no header x-sdk-version.
Acesso ao modo debug

Caso ao solicitar o endpoint /sdk.debug.js você receba um erro 403, entre em contato com a equipe Fortface para solicitar a liberação do modo debug para o seu ambiente.

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:

  1. Carregar o bootstrap oficial (/sdk.js?t=SEU_CLIENT_ID&v=VERSAO);
  2. Inicializar a SDK via FortfaceSDK.load();
  3. Obter deviceRequestInfo pelo elemento <fortface-sdk>.

Estabelecer a integridade do dispositivo​

Nosso SDK é construído como um Web Component. Na distribuição via CDN, o registro do componente é feito durante FortfaceSDK.load(). Portanto, antes de usar métodos como start() e startSession(), aguarde a resolução desse método.

Em aplicações com Server-Side Rendering (SSR), execute essa lógica apenas no browser.

Inicie a SDK e obtenha o deviceRequestInfo.

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

  const fortfaceSdk = document.querySelector('fortface-sdk');
  const deviceRequestInfo = await fortfaceSdk.start();
}
Remoção da função apllyPolyfills

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.

handshake é uma medida de segurança importante para estabelecer uma comunicação confiável entre seu back-end e API Fortface, possibilitando verificar autenticidade do dispositivo, compartilhar informações sensíveis (chaves de criptografia e sessões) e estabelecer canal seguro para troca de dados.

Com sucesso do handshake, haverá a garantia de que o dispositivo está íntegro e seu app tem as informações necessárias para prosseguir.

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

Captura​

Sabendo que a integridade do dispositivo foi estabelecida, vamos entender como iniciar a sessão.

Utilização em webviews​

Ao utilizar o Fortface SDK Web dentro de uma webview, é importante garantir que a configuração setMediaPlaybackRequiresUserGesture(boolean) esteja definida como false. Por padrão, a maioria das implementações de webview define essa configuração como true, o que impede a reprodução automática de vídeos sem interação do usuário. Essa restrição impactará a experiência de seu usuário com o Fortface SDK Web, pois impossibilita que a filmagem da câmera seja exibida automaticamente para auxiliar no seu posicionamento correto para a captura da biometria facial.

Vale destacar que, mesmo que sua aplicação não tenha sido desenvolvida especificamente em uma webview, ela pode ser executada em webviews de terceiros, como os navegadores embutidos em aplicativos como Instagram ou Telegram. Nesses cenários, geralmente mais limitados e com a configuração padrão ativa (true), o Fortface SDK Web exibirá um botão para que o usuário inicie manualmente a câmera, garantindo o consentimento necessário para iniciar a transmissão de vídeo.

Botão para iniciar a câmera

Observação: Existem casos raros em que webviews de terceiros não persistem a permissão concedida pelo usuário para acesso à câmera através do Fortface SDK Web. Nessas situações, pode ocorrer de o diálogo solicitando permissão para uso da câmera ser exibido mais de uma vez durante a experiência, exigindo que o usuário autorize novamente o acesso.

Inicialização da Sessão​

Feito o handshake, seu back-end tem as informações necessárias para que seu front-end possa inicializar a sessão na SDK, usando a função startSession.

Essa função recebe 4 parâmetros:

  1. fortfaceFinishSession (IFortfaceFinishSession): função a ser chamada após captura;
  2. sessionId (string): identificador da sessão, recebido no handshake;
  3. sessionKey (string): chave da sessão, recebida no handshake;
  4. sessionDetails (IFortfaceSessionDetails): demais controles de usabilidade para serem aplicados na sessão;

Criando callback (fortfaceFinishSession)​

A função de callback fortfaceFinishSession vai receber um objeto com a ação realizada (FortfaceActionEnum) e o resultado da ação (IFortfaceData). Com isso, é possível definir o fluxo a ser realizado após a captura:

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;
  const metrics = sessionDetails.metrics;
  // Aqui encerra o fluxo e esses são os dados para enviar para a API Fortface
}

function handleCancel(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Aqui a pessoa usuária cancelou a captura e você deve enviar o retorno dos dados para a API Fortface e seguir com o seu fluxo de cancelamento
}

function handleTimeout(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Aqui a captura foi cancelada pois o tempo esgotou. Você deve enviar o retorno dos dados para a API Fortface e seguir com fluxo de tempo limite esgotado
}

function handleTimeoutReady(fortfaceData: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const metrics = sessionDetails.metrics;
  // Aqui a captura foi cancelada pois o tempo de carregamento do ambiente da sdk esgotou. Você deve enviar o retorno dos dados para a API Fortface e seguir com fluxo de tempo limite esgotado do status de pronto
}

function handleError(data: IFortfaceData, sessionDetails: {}) {
  const data = fortfaceData.encryptData;
  const { errorCode, metrics } = sessionDetails;
  // Aqui aconteceu uma falha e você deve seguir o seu fluxo de erro
}

Demais controles de usabilidade (sessionDetails)​

O último argumento da função startSession é um objeto opcional do tipo IFortfaceSessionDetails, que permite ao desenvolvedor configurar controles adicionais de usabilidade aplicados à sessão. Esse objeto está em constante evolução, recebendo novos parâmetros à medida que funcionalidades são adicionadas ao SDK. Por isso, é recomendado sempre consultar a documentação atualizada para conhecer todos os controles disponíveis.

Atualmente, o objeto do tipo IFortfaceSessionDetails possui os seguintes campos:

  • returnMetrics: campo do tipo boolean. Quando definido como true, esse campo faz com que as métricas da sessão sejam retornadas no callback fortfaceFinishSession, acessíveis em fortfaceSessionResult.sessionDetails.metrics. Caso contrário, fortfaceSessionResult.sessionDetails.metrics será undefined. (Default: false)

  • useBackCamera: campo do tipo boolean. Quando definido como true, esse campo faz com que a câmera traseira seja usada para a captura da biometria facial. Caso contrário, o valor padrão é false e a câmera frontal será usada. (Default: false)

  • getGeolocation: campo do tipo boolean. Quando definido como true, esse campo faz com que a localização do dispositivo seja coletada para reforço nos mecanismos antifraude. Caso contrário, o valor padrão é false e a localização do dispositivo não será coletada. (Default: false)

Estado de prontidão​

Antes de iniciar a captura da biometria facial, o SDK realiza a inicialização de módulos internos essenciais para o funcionamento correto do processo. Essa etapa ocorre automaticamente e é concluída em poucos instantes. Durante esse período, o usuário verá na interface uma mensagem para aguardar a abertura da câmera, que pode ser customizada de acordo com a identidade visual da aplicação.

Caso os módulos não sejam inicializados dentro do tempo máximo configurado (por padrão, 15 segundos), o SDK será encerrado automaticamente. Nessa situação, o callback fortfaceFinishSession será acionado com fortfaceSessionResult.action igual a timeout_ready, sinalizando que a operação foi finalizada por excesso de tempo na fase de prontidão. Esse tempo limite também pode ser customizado.

Durante a captura propriamente dita, se for detectada uma falha na câmera ativa, o SDK exibirá um modal permitindo a escolha entre outras câmeras disponíveis. Cada câmera é apresentada com sua respectiva label e um preview em tempo real acima dela. Após a seleção de uma nova câmera, o fluxo será retomado automaticamente. Além disso, um novo botão será exibido abaixo da área oval de posicionamento do rosto, permitindo ao usuário trocar novamente de câmera caso tenha escolhido a incorreta. A troca de câmera só estará disponível neste cenário de falha.

Estado de prontidão

Para mais detalhes sobre como personalizar mensagens de interface, tempos de timeout e comportamento do seletor de câmera, consulte a seção customizações sdk web.

Chamando a função startSession​

const sessionId = 'resposta da API Fortface';
const sessionKey = 'resposta da API Fortface';
fortfaceSdk.startSession(fortfaceFinishSession, sessionId, sessionKey, { returnMetrics: true });

Dados mockados para exemplo:

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"

Manipulação da sessionKey

A string que representa a sessionKey contém caracteres especiais (como a quebra de linha \n) que devem ser preservados exatamente como recebidos da API Fortface. Tenha cuidado com manipulações acidentais que possam ocorrer em:

  • Inputs de formulários
  • Logs e sistemas de monitoramento
  • Processamento de strings no seu backend
  • Transferência entre serviços
  • Armazenamento em bancos de dados

Qualquer alteração nesses caracteres pode fazer com que a validação da chave falhe. Certifique-se de que a chave seja passada para o SDK exatamente como recebida da API Fortface.

Facilitação de desenvolvimento

Para desenvolvimento local do frontend exclusivamente, você pode reutilizar uma mesma sessionKey válida como mock quantas vezes forem necessárias. A restrição de uso único só é aplicada no contexto do desenvolvimento do backend, quando a API Fortface valida a chave.

Versionamento​

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

const version = await fortfaceSdk.getVersion();

Tratamento de erros​

Durante o uso do SDK Web, erros podem ocorrer em diferentes etapas da execução. Esses erros devem ser tratados de acordo com o momento em que acontecem. Existem dois cenários principais:

  1. Erros durante a execução do método start;
  2. Erros durante a captura da biometria facial, após a execução do método startSession.

Erros durante a execução do método start​

Os erros lançados durante a execução do método start são propagados como exceções, pois neste estágio ainda não existe acesso ao callback fortfaceFinishSession. Isso significa que não é possível retornar a action FortfaceActionEnum.ERROR diretamente para a aplicação.

Os erros possíveis são:

  • FORTFACE_INSECURE_PROTOCOL: O SDK está sendo executado em um ambiente não seguro (por exemplo, via HTTP).
  • FORTFACE_GENERATE_DEVICE_REQUEST_INFO_ERROR: Falha ao gerar o deviceRequestInfo, necessário para o handshake.
  • FORTFACE_INTERNAL_SETUP_ERROR: Falha na inicialização de recursos internos obrigatórios para iniciar a sessão.
  • FORTFACE_UNEXPECTED_START_ERROR: Erro inesperado ocorrido durante a execução do método start.

Para tratar esses erros, você deve utilizar o bloco try/catch para capturar a exceção:

try {
  await fortfaceSdk.start();
} catch (error) {
  const errorName = error.name;
  switch (errorName) {
    case 'FORTFACE_INSECURE_PROTOCOL':
      // Tratar erro de ambiente não seguro
      break;
    case 'FORTFACE_GENERATE_DEVICE_REQUEST_INFO_ERROR':
      // Tratar erro de geração de deviceRequestInfo
      break;
    case 'FORTFACE_INTERNAL_SETUP_ERROR':
      // Tratar erro de inicialização de recursos internos
      break;
    case 'FORTFACE_UNEXPECTED_START_ERROR':
      // Tratar erro inesperado
      break;
  }
}

Erros durante a captura da biometria facial (startSession):​

Após a execução do método startSession, eventuais erros são retornados em tempo de execução através do callback fortfaceFinishSession. Nesses casos, a action retornada será FortfaceActionEnum.ERROR, acompanhada do respectivo errorCode.

Possíveis errorCode:

  • containerTooSmall: Quando ao usar a customização embedded, o container tem um tamanho menor que o mínimo de 400x650.
  • notInitialized: O método startSession foi chamado antes do método start ter sido executado.
  • invalidSessionKey: A sessionKey fornecida está inválida.
  • detectorError: Falha no detector de pontos faciais; não foi possível localizar pontos válidos em sequência.
  • debugError: Ocorreu uma tentativa de inspecionar o SDK em modo de produção com as ferramentas de desenvolvedor do navegador.
  • cameraDisconnected: A câmera foi desconectada durante a captura e a customização showPreviewModalIfError (para escolher outra câmera) está desativada.
  • cameraUnreliable: Foram detectadas câmeras, mas nenhuma pôde ser utilizada.
  • noCompatibleVideoDevice: Nenhuma câmera compatível foi encontrada.
  • cameraPermissionDenied: O usuário negou a permissão de acesso à câmera.
  • cameraUnavailable: A câmera está indisponível (bloqueada por outro recurso ou pelo sistema).
  • cameraAccessPolicyRestricted: Acesso negado por políticas de segurança, geralmente ao executar o SDK dentro de um iframe.
  • cameraAccessUnexpectedError: Ocorreu um erro inesperado ao acessar a câmera.
  • browserUnsupported: O navegador não é compatível com a captura de biometria facial (ver seção suporte).
  • browserValidationUnexpectedError: Ocorreu um erro inesperado ao validar o navegador.
  • fileCorrupted: Exclusivo da funcionalidade de upload de documentos. Acontece quando o arquivo está corrompido.
  • fileInvalid: Exclusivo da funcionalidade de upload de documentos. Acontece quando o arquivo é inválido, como por exemplo, um PDF protegido por senha ou sem páginas.
  • fileSizeTooBig: Exclusivo da funcionalidade de upload de documentos. Acontece quando o arquivo excede o limite permitido de 5MB.

Exemplo de tratamento via callback:

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

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

      if (errorCode === 'cameraPermissionDenied') {
        // Instruir o usuário a permitir o acesso à câmera
      }

      // Adicione outros tratamentos conforme necessário
      break;
  }
}

Boas práticas recomendas​

  • Mantenha um log dos erros capturados para facilitar o diagnóstico e o suporte.
  • Oriente o usuário de forma clara quando ocorrerem erros relacionados ao navegador, à câmera ou às permissões.
  • Consulte regularmente as notas de versão do SDK para novos códigos de erro ou alterações na API.

Compatibilidade do SDK com builds de produção​

Existem alguns cenários em que aplicações que utilizam o Fortface SDK rodam sem problemas em desenvolvimento e, ainda assim, apresentam falhas somente em produção, após o build ou deploy. Em situações como essas — por exemplo, quando a câmera não abre em produção — é importante considerar como o processo de build da aplicação pode estar interferindo na execução do SDK.

Na integração via CDN, o SDK não é empacotado pelo build da sua aplicação.

Para evitar falhas em produção:

  1. Garanta que o script https://cdn-loader.isface.live/sdk.js?t=SEU_CLIENT_ID&v=VERSAO esteja presente no HTML final da aplicação, ou seja injetado no browser antes de chamar FortfaceSDK.load().
  2. Execute FortfaceSDK.load() apenas no client-side.
  3. Em aplicações com SSR, proteja o fluxo para não executar no servidor.
  4. Revise as políticas de CSP para liberar cdn-loader.isface.live e cdn.isface.live em script-src.

Typescript​

1. FortfaceSdk​

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>;
}

2. IFortfaceSessionDetails​

interface IFortfaceSessionDetails {
  returnMetrics?: boolean;
  useBackCamera?: boolean;
  getGeolocation?: boolean;
}

3. IFortfaceFinishSession​

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

4. IFortfaceSessionResult​

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

5. FortfaceActionEnum​

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

6. IFortfaceData​

interface IFortfaceData {
  encryptData?: {
    data: string;
    imgData?: string;
    key: string;
  };
  imgPreview?: string;
}

7. 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',
  containerTooSmall = 'containerTooSmall',
}

8. IFortfaceReturnMetrics​

interface IFortfaceReturnMetrics {
  downloadFiles: number;
  openCamera: number;
  totalCaptureTime: number;
  captureTime: number;
}

9. IFortfaceCustomizer​

interface IFortfaceCustomizer {
  base?: IFortfaceBase;
  camera: IFortfaceCamera;
  cameraPreview: IFortfaceCameraPreview;
  instructions: IFortfaceInstructions;
  modal?: IFortfaceModal;
  embedded?: IFortfaceEmbedded;
}

10. IFortfaceBase​

export interface IFortfaceBase {
  timeout?: number;
}

11. IFortfaceCamera​

interface IFortfaceCamera {
  timeout?: number;
  cancelButtonImage?: string;
  showCancelButton?: boolean;
  alertColor?: string;
  successColor?: string;
  loadingColor?: string;
  loadingStroke?: string;
  facePositioned?: string;
  faceFar?: string;
  faceNear?: string;
  noFace?: string;
  facePitchIsUp?: string;
  facePitchIsDown?: string;
  noFaceYaw?: string;
  faceRollLeft?: string;
  faceRollRight?: string;
  faceCenterLeft?: string;
  faceCenterRight?: string;
  faceCenterUp?: string;
  faceCenterDown?: string;
  brightnessEvaluation?: {
    lowBrightnessMessage?: string;
    highBrightnessMessage?: string;
    lowBrightnessIcon?: string;
    highBrightnessIcon?: string;
    iconBackgroundColor?: string;
    feedbackColor?: string;
    validationTimeout?: number;
  };
  frameTextVisible?: boolean;
  switchCameraButtonVisible?: boolean;
  waitCameraDescription?: string;
  background?: string;
  font?: string;
  textColor?: string;
  logo?: string;
  changeCameraButtonBgColor?: string;
  changeCameraButtonTextColor?: string;
  changeCameraButtonRadius?: string;
  webviewPlayButtonBgColor?: string;
  webviewPlayButtonTextColor?: string;
  webviewPlayButtonRadius?: string;
  webviewPlayButtonDescription?: string;
}

12. IFortfaceCameraPreview​

interface IFortfaceCameraPreview {
  showPreviewModalIfError?: boolean;
  title?: string;
  background?: string;
  radioColor?: string;
  buttonBgColor?: string;
  buttonRadius?: string;
  buttonTextColor?: string;
}

13. IFortfaceInstructions​

interface IFortfaceInstructions {
  showInstructions?: boolean;
  background?: string;
  buttonBgColor?: string;
  buttonRadius?: string;
  buttonTextColor?: string;
  iconColor?: string;
  textColor?: string;
  cancelButtonImage?: string;
  showCancelButton?: boolean;
  font?: string;
  title?: string;
  noItemsMessage?: string;
  placeMessage?: string;
  expressionMessage?: string;
  positionMessage?: string;
  backgroundIconColor?: string;
}

14. IFortfaceModal​

export interface IFortfaceModal {
  available?: boolean;
  overlayColor?: string;
  overlayOpacity?: string;
  minScreenWidth?: number;
}

15. IFortfaceEmbedded​

export interface IFortfaceEmbedded {
  enabled?: boolean;
}

Callback de erro, cancelamento, timeout e timeout_ready​

Quando uma tentativa de captura do rosto do usuário não é completada com sucesso, por exemplo quando o usuário cancela a captura, quando a captura não acontece durante o tempo determinado, ou o tempo determinado de prontidão do motor de identificação, é importante que o acontecimento deste evento seja enviado ao backend para termos corretas métricas de sucesso ou falhas das capturas.

O SessionEngineResult recebido na função finishedSessionEngine é um objeto que possui 3 propriedades: data, action (ação realizada na SDK) e pode conter sessionDetails, em caso de erro.

Como visto anteriormente no tópico Captura, o data contém dados criptografados e pode ser convertidos em JSON. Entretanto, diferentemente da captura, neste cenário após a conversão para JSON, teremos somente os seguintes campos:

{
    key: String,
    data: String,
}

Lembrete: As chaves key e data são geradas pela SDK, enviadas ao seu back-end e então à API Fortface.​

Exemplo de implementação​

  1. Identificamos na SDK que houve um cancelamento de captura.
  2. Criamos o objeto criptografado.
  3. Terminamos a SDK e enviamos o payload gerado e a ação realizada.
  4. No app de implementação, dentro da função startSession tem o primeiro parâmetro sendo uma função de callback, onde é retornado o resultado da SDK.

// Função de callback com tratamento de seus status

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;
  }
};

Suporte​

As versões mínimas para cada navegador que nosso SDK Web suporta estão listadas abaixo:

Android:

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

iOS:

  • Versão mínima do iOS para todos os navegadores: 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

Resumo​

  1. Download da SDK;
  2. Instalação;
  3. Capturar o deviceRequestInfo;
  4. Fazer handshake API Fortface (via seu backend);
  5. Criar função de callback;
  6. Iniciar sessão;
  7. Receber os dados (data, imgData, key);
  8. Enviar para API Fortface (via seu backend);
  9. Receber resposta da API Fortface e seguir com sua regra de negócio;
Última atualização em por Dionnatas Santa Fé Filho