Resolução de Problemas SDKs Nativos

Introdução​

Bem-vindo à página de resolução de problemas dos SDKs nativos da Fortface. Aqui você encontrará soluções para erros comuns, problemas de configuração e dúvidas frequentes relacionadas ao uso dos SDKs 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

  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 Android​

Os problemas listados à seguir afetam apenas o SDK Android.

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

  1. No AndroidManifest.xml, configure a Activity principal como singleTop:
<activity
    android:name=".MainActivity"
    android:launchMode="singleTop">
</activity>
  1. 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

  1. Garanta que o build de produção não tenha debuggable true e esteja assinado com keystore de release.
  2. Teste um APK de release sem shrinker (R8/ProGuard); se o erro sumir, ajuste regras ou desabilite otimizações que removem metadados relevantes.
  3. 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.
Última atualização em