Pular para o conteúdo principal

Boas Práticas para Implementação de SDK

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​

Use uma PoC para facilitar sua implementação

A Unico oferece Proofs of Concept (PoCs) com exemplos de código funcional para todas as linguagens suportadas. Elas demonstram as sequências de métodos esperadas e os padrões de integração. Acesse as PoCs disponíveis por meio do sistema de tickets de suporte do portal do cliente.

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:

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.

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
Última atualização em