Boas Práticas

Markdown

Esta página consolida as principais diretrizes para integrar e manter os SDKs da Unico. Seguir essas práticas reduz erros de integração, previne incidentes de segurança e garante uma implantação em produção tranquila.

Primeiros passos

Comece a partir de um aplicativo de referência

A Unico oferece um aplicativo de referência para cada SDK no repositório reference-apps. Cada aplicativo implementa a jornada completa do usuário.

Mantenha sempre seus SDKs atualizados

Os SDKs evoluem continuamente para oferecer maior segurança e novos recursos. Aplicar atualizações prontamente — especialmente as críticas — é essencial. Consulte a Política de Atualização para prazos e obrigações.

Identifique a versão mais recente disponível

Verifique a versão atual de cada plataforma nas respectivas notas de versão:

• Notas de versão Android
• Notas de versão iOS
• Notas de versão Flutter
• Web — Notas de versão do SDK de Jornadas

Estratégia de atualização

Evite atualizar o SDK e outros componentes simultaneamente

Seu aplicativo provavelmente carrega múltiplas bibliotecas junto com o SDK da Unico. Atualizar várias dependências ao mesmo tempo dificulta a identificação da causa raiz de falhas. Atualize o SDK de forma isolada e valide-o em um ambiente de homologação antes de combiná-lo com outras mudanças.

Obtendo ajuda com uma atualização de SDK

Ao abrir um ticket de suporte para problemas de atualização, inclua:

• Linguagem do SDK e tipo de implementação (nativa ou híbrida)
• Framework utilizado
• Versão atual e versão alvo
• API Key
• Descrição das alterações e passos para reproduzir
• Resultados, erros, logs, capturas de tela ou vídeos

Segurança do JWT

Não manipule o objeto JWT

Não abra nem modifique o JWT criptografado

O JWT retornado após uma captura bem-sucedida é criptografado. Não o abra, analise nem serialize. Sua estrutura interna pode mudar sem aviso prévio. Use-o exclusivamente ao enviar imagens para as APIs da Unico.

Para pré-visualizações de imagem, use o atributo Base64 fornecido junto ao JWT — nunca decodifique o próprio JWT.

Envie o JWT dentro de 10 minutos

aviso

Por razões de segurança, o JWT deve ser enviado ao backend da Unico dentro de 10 minutos após a captura. Pacotes enviados após esse prazo são invalidados.

Envie o JWT apenas uma vez

aviso

O JWT deve ser submetido apenas uma vez. Se ocorrer um erro durante o envio, uma nova captura biométrica deve ser realizada — não reutilize o mesmo JWT.

Diretrizes de teste

Não use virtualização ou emuladores

Executar o SDK em máquinas virtuais ou emuladores aciona códigos de erro de segurança (73006, 73600, 73400). Sempre teste em dispositivos físicos para evitar a identificação equivocada de erros e retrabalho desnecessário.

Não mantenha o DevTools aberto durante capturas web

O SDK Web detecta o DevTools aberto como um possível sinal de fraude e invalida o envio. Feche o DevTools antes de executar testes de captura de ponta a ponta.

Realize testes no ambiente de homologação da Unico

Antes de ir para produção, execute testes completos no ambiente de homologação da Unico com cenários realistas. Use API Keys e configurações específicas do ambiente de homologação — nunca use credenciais de produção em testes.

O ambiente de homologação (UAT) do IDCloud aplica os mesmos critérios de segurança da produção. As diretrizes abaixo explicam por quê e como testar sem interrupções.

O que mudou na homologação

Antes — detectava, mas não recusava Condições fora do padrão de um uso real eram identificadas, mas não impediam a captura.

Agora — detecta e recusa As mesmas condições passam a gerar recusa de prova de vida, com o mesmo rigor da produção.

Por que essa restrição existe

Fidelidade — similaridade com a produção O que passa em homologação deve funcionar da mesma forma em produção — evitando que uma integração aprovada em testes falhe de forma inesperada depois do go-live.

O que você pode e não pode fazer

Testando em condições próximas ao uso real, as camadas de segurança não impactam seu desenvolvimento.

Ferramentas de desenvolvimento que não sejam as padrões utilizadas pelo mercado acionam validações de segurança, e a transação pode ser barrada.

Cenário	Situação
Fluxo completo da integração — captura, envio, resposta da API e retorno	✅ Pode
Cenários funcionais: UI/UX, performance, erros de negócio	✅ Pode
Dispositivo na configuração padrão de um usuário final	✅ Pode
Integração com backend, APIs e processamento de dados	✅ Pode
Dispositivo com root/jailbreak	❌ Não pode
Modo debug / depuração USB ativa	❌ Não pode
Emuladores ou virtualização	❌ Não pode
Câmeras virtuais ou ferramentas de automação de captura	❌ Não pode
Ferramentas que alterem a conexão	❌ Não pode
MDM corporativo ou monitoramento ativo no dispositivo	❌ Não pode
Sandbox em container ou máquina virtual	❌ Não pode

Qualquer uma dessas condições pode gerar recusa de prova de vida.

Seu ciclo de QA depende de uma dessas condições?

Fale com o time de suporte para orientação sobre a configuração do seu ambiente. Não há exceção, liberação pontual ou flexibilização temporária — a Unico mantém a homologação equalizada à produção enquanto entender necessário.

Diretrizes específicas por plataforma

Flutter: use o plugin Flutter da Unico

Não tente fazer bridge dos SDKs nativos Android ou iOS dentro de um aplicativo Flutter. Bridges nativos frequentemente produzem erros não mapeados. Sempre use o plugin Flutter dedicado da Unico.

Web: exclua arquivos de recursos antigos ao atualizar versões

Ao atualizar o SDK Web, exclua os arquivos de recursos antigos da sua pasta public antes de inserir os novos. Arquivos com nomes idênticos não serão sobrescritos automaticamente e podem causar conflitos de versão.

Mobile: limpe o cache antes de compilar novas versões

Artefatos de compilação de versões anteriores do SDK podem causar erros de dependência após uma atualização. Antes de compilar uma nova versão:

• Flutter: exclua pubspec.lock e execute flutter pub get
• iOS: execute pod cache clean --all e pod install
• Android: execute ./gradlew clean

Configurações de ofuscação

Exclua o código do SDK da Unico da sua configuração de ofuscação. Ofuscar o SDK comumente causa falhas em builds de release que não aparecem em builds de debug. Consulte a documentação específica da plataforma para as regras de exceção necessárias.

UX e performance

Separe o fluxo de preparação e abertura da câmera em duas etapas

Estruture o fluxo do SDK em duas etapas distintas:

1. Preparar — inicialize o SDK enquanto a página está carregando (antes da interação do usuário).
2. Abrir — abra a câmera somente quando o usuário acionar a ação explicitamente.

Preparar o SDK com antecedência reduz a latência percebida e melhora significativamente a experiência do usuário.

Implantação em produção

Crie um checklist seguro para implantação em produção

Antes de implantar em produção, verifique:

• API Keys de produção e configurações de ambiente estão corretas
• Plano de rollback está definido e testado
• Protocolo de coleta de logs está implementado
• Procedimentos de ticket de suporte estão documentados para tratamento de falhas
• Todas as validações passaram no ambiente de homologação