--- title: Boas Práticas description: Diretrizes para integrar, atualizar, testar e publicar os SDKs da Unico com segurança, incluindo as regras do ambiente de homologação (UAT). canonical: https://developer.unico.io/pt-BR/developers/sdks-and-tools/best-practices-for-sdk-implementation locale: pt-BR generated_by: markdown-export --- - [/pt-BR/](/pt-BR/) - [SDKs e Ferramentas](/pt-BR/developers/sdks-and-tools/overview) - Boas Práticas **Nesta página# Boas Práticas 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](https://github.com/unico-labs/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](/pt-BR/developers/sdks-and-tools/update-policy) 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](/pt-BR/developers/sdks-and-tools/android/resources/release-notes) [Notas de versão iOS](/pt-BR/developers/sdks-and-tools/ios/resources/release-notes) [Notas de versão Flutter](/pt-BR/developers/sdks-and-tools/flutter/resources/release-notes) [Web — Notas de versão do SDK de Jornadas](/pt-BR/developers/sdks-and-tools/web/resources/release-notes) ### 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](#perform-tests-in-unicos-staging-environment) 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 criptografadoO 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 avisoPor 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 avisoO 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árioSituaçãoFluxo completo da integração — captura, envio, resposta da API e retorno✅ PodeCenários funcionais: UI/UX, performance, erros de negócio✅ PodeDispositivo na configuração padrão de um usuário final✅ PodeIntegração com backend, APIs e processamento de dados✅ PodeDispositivo com root/jailbreak❌ Não podeModo debug / depuração USB ativa❌ Não podeEmuladores ou virtualização❌ Não podeCâmeras virtuais ou ferramentas de automação de captura❌ Não podeFerramentas que alterem a conexão❌ Não podeMDM corporativo ou monitoramento ativo no dispositivo❌ Não podeSandbox 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](https://business.unico.io/hc/) 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: **Preparar** — inicialize o SDK enquanto a página está carregando (antes da interação do usuário). **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 23 de out. de 2026**