Resolução de problemas

Introdução​

Bem-vindo à página de resolução de problemas do SDK Web da Fortface. Aqui você encontrará soluções para erros comuns, problemas de configuração e dúvidas frequentes relacionadas ao uso do SDK Web.

Problemas gerais​

Os problemas listados à seguir afetam qualquer SDK, independentemente da plataforma.

Erro ao iniciar sessão​

Sintoma: ao chamar startSession, o SDK retorna erro de validação informando que a sessionKey é inválida.

Causa raiz: a aplicação recebe sessionToken, sessionKey e sessionId da API, mas a sessionKey é alterada (ex.: remove \n, aplica trim, reescapa aspas, muda encoding, compacta JSON ou passa por inputs/serializações que transformam o texto).

Diagnóstico rápido

  • Teste no ambiente que falha colando a sessionKey exatamente como retornou da API; se passar a funcionar, houve alteração no transporte.
  • Compare (hash ou tamanho) a chave recebida x a chave entregue ao SDK; qualquer diferença indica mutação.
  • Verifique camadas de transporte (forms, JSON.stringify/parse, sanitizações, storage) que possam remover quebras de linha ou escapar caracteres.

Correção

  1. Confirme que os três campos (sessionToken, sessionKey, sessionId) chegam ao front sem transformações.
  2. Garanta que a sessionKey seja armazenada e entregue ao SDK exatamente como veio, incluindo quebras de linha.
  3. Evite qualquer validação, parse, reestruturação ou sanitização na sessionKey — trate-a como um blob opaco.

Problemas de integração com o SDK Web​

Os problemas listados à seguir afetam apenas o SDK Web.

DevTools trava ao inspecionar o SDK​

Sintoma: abrir DevTools congela/entra em loop de breakpoints ao inspecionar o SDK.

Causa raiz: proteções antifraude da versão de produção disparam breakpoints contínuos com DevTools aberto.

Correção

  • Em desenvolvimento, use o SDK Web em debug-mode (um único breakpoint, inspeção liberada).
  • Em produção, sempre use a versão oficial (não debug-mode), com DevTools fechado pelo usuário final.

Alta ocorrência de erro cameraPermissionDenied​

Sintoma: o SDK Web retorna cameraPermissionDenied em todas as tentativas; o prompt não reaparece.

Causa raiz: o usuário negou a permissão; navegadores não reexibem o popup após a negativa e bloqueiam novas solicitações.

Correção

  • Não faça retentativas em loop. Trate o erro e oriente o usuário a liberar a câmera nas configurações do navegador e recarregar a página.
  • Informe antes que a câmera será usada para reduzir bloqueios imediatos.

Considerações importantes para uso em WebViews​

Sintoma: na WebView o vídeo não aparece automaticamente ou mostra um botão de consentimento, diferente do navegador.

Causa raiz: WebViews bloqueiam autoplay de mídia; o vídeo do SDK obedece essa restrição.

Correção (configure antes de carregar a página):

webView.settings.mediaPlaybackRequiresUserGesture = true // Android
webView.configuration.mediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypeNone // iOS

SDK fica preso na mensagem de aguarde e não abre a câmera​

Sintoma: o SDK fica em “aguarde” (Skeleton) e a câmera nunca aparece; o ícone da câmera pode acender.

Causa raiz: outro código abriu getUserMedia e manteve o track ativo, bloqueando o dispositivo.

Correção

  1. Se abrir a câmera antes do SDK, feche os tracks antes de iniciar:
const tracks = await navigator.mediaDevices.getUserMedia({ video: true });
// ... uso ...
tracks.getTracks().forEach((track) => track.stop());
  1. Depois de liberar, inicie o SDK:
fortfaceSdk.start();
fortfaceSdk.startSession(fortfaceFinishSession, sessionId, sessionKey);
  1. Para checar permissão sem travar a câmera, use navigator.permissions.query({ name: "camera" }).
  2. Confirme que nenhum outro componente (barcode/QR etc.) mantém a câmera ativa em paralelo.

SDK para de funcionar quando executado em builds de produção​

Sintoma: em dev funciona, mas em produção a câmera não abre, fica no Skeleton ou o SDK deixa de injetar elementos/estilos.

Causa raiz: minificação/otimização do build remove ou altera inicializações do SDK (custom elements, side effects).

Correção

  • Não minifique o pacote fortface-sdk em node_modules. Deixe o restante do app minificado.
Exemplo (Next.js < 15 com Terser)​
// next.config.mjs
import TerserPlugin from 'terser-webpack-plugin';

const nextConfig = {
  output: 'export',
  webpack: (config, { isServer }) => {
    if (!isServer) {
      const excludeFortface = /node_modules[\\/](fortface-sdk)([\\/]|$)/;
      config.optimization = {
        ...config.optimization,
        minimize: true,
        minimizer: [
          new TerserPlugin({
            exclude: excludeFortface,
          }),
        ],
      };
    }
    return config;
  },
};

export default nextConfig;

Alternativa (sem bundler)

  • Extraia o .tgz, copie package/dist/fortface-sdk para assets/vendor e importe direto:
<script type="module" src="/vendor/fortface-sdk/fortface-sdk.esm.js"></script>
  • Adicione vendor/fortface-sdk/ ao .eslintignore para evitar falsos positivos do lint.

SDK usando Angular com problemas no iOS 26.2​

Sintoma: Ocorre problemas na inicialização quando se utiliza o pacote .tgz do fortface.

Causa raiz: Após última atualização do iOS para a versão 26.

Correção: Utilização sem fortface .tzg (com bundler)

Alternativa (sem bundler)

  • Extraia o .tgz, copie package/dist/fortface-sdk para assets/vendor e importe direto:
<script type="module" src="/vendor/fortface-sdk/fortface-sdk.esm.js"></script>
  • Adicione vendor/fortface-sdk/ ao .eslintignore para evitar falsos positivos do lint.

Versão CSP (Content Security Policy)​

Sintoma: Ocorre problemas na utilização do sdk ao ter configurações de CSP.

Correção:

  • Utilização da versão fortface-sdk.x.x.x-csp.tgz. Veja a página Versão CSP para a lista completa de diretivas necessárias.
Última atualização em