Resolução de Problemas

Introdução

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

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

Confirme que os três campos (sessionToken, sessionKey, sessionId) chegam ao front sem transformações.
Garanta que a sessionKey seja armazenada e entregue ao SDK exatamente como veio, incluindo quebras de linha.
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 Android

Os problemas listados à seguir afetam apenas o SDK Android.

Navegação parece “sair do app” ao iniciar o SDK

Sintoma: ao iniciar o SDK, o app parece abrir outra tela/Activity, como se saísse do fluxo atual.

Causa raiz: android:launchMode da Activity principal provavelmente está como standard (padrão), criando nova instância ao iniciar o SDK.

Correção

No AndroidManifest.xml, configure a Activity principal como singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="singleTop">
</activity>

Recompile e valide que o fluxo permanece na mesma Activity.

Exceção "There's something wrong!" ao iniciar o SDK

Sintoma: start() lança exceção "There's something wrong!" quando isDebugMode está como false.

Causa raiz: o app ainda é percebido como build de debug (ou híbrido) mesmo tentando iniciar o SDK em “produção”.

Checklist de diagnóstico

Build variant atual está debuggable no build.gradle?
App foi assinado com keystore de debug?
- Execute o comando apksigner verify --print-certs <app-release.apk> para verificar.
- Debug keystore irá retornar algo como CN=Android Debug, O=Android, C=US
R8/ProGuard removeu metadados ou reescreveu flags que o SDK usa para validar ambiente?
Há flavors/combinações release+debug ou APKs híbridos (RN/Flutter/Capacitor) sendo usados?

Correção

Garanta que o build de produção não tenha debuggable true e esteja assinado com keystore de release.
Teste um APK de release sem shrinker (R8/ProGuard); se o erro sumir, ajuste regras ou desabilite otimizações que removem metadados relevantes.
Revalide isDebugMode=false apenas quando o app estiver, de fato, em release.

SDK parou de funcionar após ofuscação (ProGuard/R8)

O Fortface SDK já é ofuscado e minificado internamente. Porém, na build de release de sua aplicação, ferramentas como R8/ProGuard podem renomear ou eliminar classes críticas, causando falhas silenciosas. Adicione regras de keep para evitar esse problema.

Adicione a seguinte regra no arquivo proguard-rules.pro:

-keep class br.com.fortface.sdk.** { *; }

Após aplicar a regra:

Limpe e gere um APK de release.
Teste o fluxo do SDK; se persistir, verifique se há outras regras globais removendo recursos reflexivos.

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

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

Depois de liberar, inicie o SDK:

fortfaceSdk.start();
fortfaceSdk.startSession(fortfaceFinishSession, sessionId, sessionKey);

Para checar permissão sem travar a câmera, use navigator.permissions.query({ name: "camera" }).
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

directives: {
  defaultSrc: ["'self'"],
  scriptSrc: ["'self'", "https://cdn.isface.live", "'unsafe-eval'", "'wasm-unsafe-eval'"],
  styleSrc: ["'self'", "https://cdn.isface.live", "'unsafe-inline'"],
  imgSrc: ["'self'", "data:"],
  connectSrc: ["'self'", "https://cdn.isface.live", "data:", "blob:"],
  fontSrc: ["'self'", "https://cdn.isface.live"],
  frameSrc: ["'none'"],
  frameAncestors: ["'none'"],
  workerSrc: ["'self'", "blob:"],
  childSrc: ["'none'"],
  objectSrc: ["'none'"],
  mediaSrc: ["'none'"],
  baseUri: ["'self'"],
  formAction: ["'self'"],
  manifestSrc: ["'self'"],
  upgradeInsecureRequests: [],
},

Introdução​

Problemas gerais​

Erro ao iniciar sessão​

Problemas de integração com o SDK Android​

Navegação parece “sair do app” ao iniciar o SDK​

Exceção "There's something wrong!" ao iniciar o SDK​

SDK parou de funcionar após ofuscação (ProGuard/R8)​

Problemas de integração com o SDK Web​

DevTools trava ao inspecionar o SDK​

Alta ocorrência de erro cameraPermissionDenied​

Considerações importantes para uso em WebViews​

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

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

Exemplo (Next.js < 15 com Terser)​

SDK usando Angular com problemas no iOS 26.2​

Versão CSP (Content Security Policy)​

Introdução

Problemas gerais

Erro ao iniciar sessão

Problemas de integração com o SDK Android

Navegação parece “sair do app” ao iniciar o SDK

Exceção "There's something wrong!" ao iniciar o SDK

SDK parou de funcionar após ofuscação (ProGuard/R8)

Problemas de integração com o SDK Web

DevTools trava ao inspecionar o SDK

Alta ocorrência de erro `cameraPermissionDenied`

Considerações importantes para uso em WebViews

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

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

Exemplo (Next.js < 15 com Terser)

SDK usando Angular com problemas no iOS 26.2

Versão CSP (Content Security Policy)