Integração Fortface SDK Web no seu web app

Como funciona?​

Nossa SDK tem como objetivo efetuar a captura ou o upload 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');

        // Captura de documentos
        const deviceRequestInfo = await fortfaceSdk.startDoc();

        // Upload de documentos
        // const deviceRequestInfo = await fortfaceSdk.startDocUpload();
      }

      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.startDoc();
  });
</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 startDoc(), startDocUpload(), startSessionDoc() e startSessionDocUpload(), 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');

  // Para captura de documentos
  const deviceRequestInfo = await fortfaceSdk.startDoc();

  // Para upload de documentos
  // const deviceRequestInfo = await fortfaceSdk.startDocUpload();
}
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.

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

Captura e Upload de Documentos​

Limite de Tamanho

O tamanho máximo de um arquivo (PDF/Imagem) para upload é de 4MB. Arquivos maiores serão rejeitados com o código de erro fileSizeTooBig.

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

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 startSessionDoc para a captura de documentos, ou a função startSessionDocUpload para o upload de documentos.

Essa função recebe 3 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;

Criando callback​

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; // Disponível apenas na funcionalidade de captura de documentos
  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 (ou o upload) 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
}

ATENÇÃO!!​

  • O fluxo é feito para cada "face" do documento, ou seja, frente e verso. Cada um deve ser feito o fluxo completo, passando pelo startDoc (ou StartDocUpload), handshake e startSessionDoc (ou startSessionDocUpload)

Chamando a função startSessionDoc / startSessionDocUpload​

const sessionId = 'resposta da API Fortface';
const sessionKey = 'resposta da API Fortface';
fortfaceSdk.startSessionDoc(fortfaceFinishSession, sessionId, sessionKey); // Para a captura de documentos
fortfaceSdk.startSessionDocUpload(fortfaceFinishSession, sessionId, sessionKey); // Para o upload de documentos

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 startDoc ou startDocUpload;
  2. Erros durante a captura do documento, após a execução do método startSessionDoc ou startSessionDocUpload.

Erros durante a execução do método startDoc ou startDocUpload​

Os erros lançados durante a execução do método startDoc ou startDocUpload 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 startDoc ou startDocUpload.

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 do documento (startSessionDoc ou startSessionDocUpload):​

Após a execução do método startSessionDoc ou startSessionDocUpload, 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:

  • notInitialized: O método startSessionDoc ou startSessionDocUpload foi chamado antes do método startDoc ou startDocUpload (respectivamente) 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>;
  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; // Disponível apenas na funcionalidade de captura de documentos
}

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

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 (apenas para captura de documentos), ou o tempo determinado de prontidão do motor de identificação (apenas para captura de documentos), é 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