Melhores Práticas de Implementação SDK

Veja abaixo as melhores práticas para implementação da SDK da Unico, para solucionar os problemas mais recorrentes:

Utilize uma POC para facilitar sua implementação
A Unico fornece um conjunto de POCs (Prova de Conceito), que são implementações nas diversas linguagens suportadas pela SDK, que apresentam exemplos funcionais de código com os fluxos e métodos no contexto da SDK, para fins didáticos, facilitando o entendimento da sequência esperada e sua adaptação para o código a ser implementado pelos nossos clientes.
Você pode consultar as POCs disponíveis neste site e solicitá-las via abertura de ticket em nossa página de atendimento.

Mantenha sempre suas SDKs atualizadas
Constantemente as SDKs vêm evoluindo para garantir maior segurança e novos recursos e funcionalidades. É essencial que os clientes mantenham uma rotina de atualizações, e agilidade em atualizações críticas.

Para mais detalhes, consulte a política de atualizações das SDKs.

Evite atualizar a SDK e outros componentes/funcionalidades ao mesmo tempo
Como boa prática de atualização, evite realizar o processo de upgrade de nossa SDK ao mesmo tempo em que atualiza outra funcionalidade/biblioteca. Ao se deparar com uma falha e/ou mudança de comportamento, pode ser um desafio entender o que está sendo a causa raiz.
Recomendamos realizar as atualizações separadamente, para garantir maior controle das validações, além de utilizar o nosso ambiente de homologação.

Não leia ou manipule o objeto JWT (Encrypted)
Ao efetuar uma captura de imagem com sucesso, o método onSuccessSelfie retorna um objeto do tipo ResultCamera que possui 2 atributos:

  • Base64: que pode ser utilizado para exibição de uma prévia da imagem em seu app.
  • Encrypted: que é um objeto JWT que deve ser deve ser enviado na chamada das APIs REST. O JWT (Encrypted) deve ser utilizado estritamente durante o envio da imagem através das APIs da Unico. Não se deve abrir e/ou serializar esse atributo, suas características podem ser alteradas sem aviso prévio. Seu uso deve ser exclusivo nas interações com as APIs, para garantir a integridade e segurança dos dados.
    A Unico não se responsabiliza por quaisquer danos decorrentes dessa prática, uma vez que as modificações podem ocorrer de maneira imprevista. Como dito, a SDK já fornece o atributo Base64 para obter a imagem em questão.

Um caso de exemplo em Swift: Método: onSuccessSelfie print("(result.encrypted)") para Encrypted print("(result.base64)") para para Base64 print("(result)") para Encrypted e Base64.

Envio do JWT dentro de 10 minutos
Por motivos de segurança, o envio da JWT deve ser realizado dentro de um período de 10 minutos. Caso o envio supere esta janela, o pacote será considerado inválido. Considere este tempo no momento da jornada do usuário em seu aplicativo e evite mudanças posteriores.

Não utilize virtualização
A virtualização de dispositivos nas dinâmicas de testes do seu aplicativo pode ser interpretada como uma tentativa de burlar as camadas de segurança incorporadas ao provedor de biometria, podendo retornar os erros:

  • Mobile
    73006 - Unable to open camera on emulators.
  • Web
    73600 - Could not find camera resource.
    73400 - Could not initialize camera. 

Para evitar retrabalho e a identificação errônea de erros, os testes devem ser realizados em dispositivos físicos.

Utilizar a mesma API Key para captura e envio da foto para o backend
Toda comunicação e requisição é baseada em API Keys definidas previamente na instância do cliente. É necessário que sua implementação utilize a mesma API Key no fluxo de captura e no fluxo de envio, evitando erros de integração, e facilitando a validação e a rastreabilidade dos processos e fluxos.

Em caso de dúvidas sobre sua API Key, acesse o suporte técnico.

Não manter o DevTools aberto enquanto realiza capturas Web
No processo de realização de testes e validações, é normal manter o DevTools aberto para verificação de fluxos e requisições. No entanto, não deve-se considerar o método de validação de captura nesses testes, já que a SDK identifica como possível fraude e invalida a passagem quando enviada ao backend. Quando houver a realização de fluxos ponta-a-ponta, é essencial manter o DevTools desativado e seguir com a captura normal.

Excluir arquivos resources quando for identificado na atualização de novas versões (WEB)
Ao subir versões para a SDK WEB e houver atualização de arquivos resources, é necessário excluir o arquivo antigo e inserir os novos na pasta Public. Essa ação deve ser realizada para evitar que  arquivos estejam com o mesmo nome e não sejam substituídos. Certifique-se também de verificar se não há cache internamente dos arquivos resources antigos após a atualização e novo build.

Implementações em aplicações Flutter devem ser feitas utilizando nosso plugin Flutter
Para a implementação em aplicações flutter, sempre utilize o nosso plugin de flutter específico para este propósito. Reforçamos que não tente implementar as versões nativas da nossa SDK (Android/IOS) através de bridges em aplicações flutter, esta ação pode gerar erros que não foram mapeados pelo time de engenharia da Unico.

Separar o fluxo de preparação e abertura de câmera em 2 etapas
A implementação da SDK possui dua etapas até a captura da foto e geração do encrypted:

  • Preparação da câmera
    Na etapa de preparação, é preciso passar o tipo de câmera a ser utilizado e o bundle com as informações de API KEY. Caso esteja correto, a autenticação com o backend da SDK será realizada com sucesso.
  • Abertura da câmera
    A etapa de abertura câmera normalmente é realizada a partir de um clique de botão do usuário. A autenticação com o backend da SDK pode levar alguns segundos, então colocar essa etapa junto com a abertura de câmera pode gerar uma frustração e sensação de lentidão. Dessa forma, o ideal é que durante o carregamento da página de orientações de captura, a preparação da câmera já esteja sendo feita, assim, quando o usuário decidir abrir a câmera, o carregamento será mais rápido e a experiência final melhor.

Limpeza de cache ao atualizar a SDK mobile
Sempre realize a limpeza de cache antes de realizar o build e subir novas versões. Caso esta limpeza não seja realizada, é possível se deparar com erros relacionados a cache de dependências que possivelmente tenham sido removidas ou atualizadas em novas versões. Veja abaixo alguns exemplos de como realizar:

  • Para o Flutter seguir com o comando:
    - Remova o arquivo pubspec.lock;
    - Ou flutter pub get.
  • Para o IOS seguir com o comando:
    - pod cache clean 'unicocheck-ios' –all
    - Ou pod cache clean –all
    - Ou remover o podfile.lock e seguir com o pod install.
  • Para o Android no build Gradle seguir com o comando:
    - ./gradlew clean

Retornos 511 - Centralize o rosto na área de captura
O retorno 511 não é uma falha (um código de erro) da SDK no contexto da captura. Ele pode retornar em algumas situações:

  • Quando o aplicativo está tentando realizar um processo e enviando um JWT que já está expirado (limite de 10min após ser gerado), ou que já foi utilizado em um processo anterior. Se este for o caso, é necessário rever a jornada de seu usuário.
  • Também pode ser retornar quando a SDK não localizar uma face na imagem de captura e, isso pode ser devido a diversos fatores, tais como: luminosidade ruim do local onde foi tirada a foto, por objetos que a pessoa esteja usando no momento da captura (como boné, brincos, headphone, óculos - mais detalhes neste tópico).

Configurações de ofuscação
O ofuscamento é um processo de transformar o bytecode em uma forma menos legível por humanos, dificultando a engenharia reversa. A ferramenta de ofuscação que você utiliza em sua aplicação pode afetar o funcionamento da SDK, portanto é necessário que o mesmo não ofusque o código da SDK. Um bom indicador para problemas de ofuscação, é verificar se sua aplicação funciona em modo debug e deixa de funcionar quando realiza o build em modo release, uma vez que a ofuscação não modifica os arquivos em modo debug.

Sendo assim, é necessário que durante a implementação da SDK, você adicione às suas regras de ofuscação a configuração para a SDK Unico, caso contrário, enfrentará problemas ao tentar buildar o projeto utilizando o SDK IOS, Android ou Flutter.

Abaixo estão disponíveis os links para as configurações de ofuscação de cada OS:

Realize testes e validações no ambiente de homologação da unico
A Unico fornece um ambiente de homologação para que os clientes possam realizar testes e validações de suas implementações antes de realizar qualquer mudança e alteração no ambiente de produção. Reforçamos a importância desta etapa, a fim de garantir maior segurança quando for realizar a janela de mudança em produção. Garanta que seu plano de testes inclua o máximo de validações e cenários que encontrará no ambiente de produção (como variação de dispositivos, testes com limitação de conectividade, etc)
Importante: lembre-se que o ambiente de homologação possui seu próprio conjunto de parametrizações/configurações, como conta de serviço e API Keys específicas (diferentes do ambiente de produção).

Crie um roteiro seguro para entrada em produção

  • Crie um roteiro/checklist levando em conta o plano de gestão de mudanças da sua empresa.
  • Certifique-se que esteja utilizando as configurações corretas de produção (como API Key correta).
  • Garanta que tenha um plano de rollback (recovery) em caso de falha ao subir a nova versão em produção.
  • Ao se deparar com uma falha, colete todos os logs e insumos.
  • Reative a versão anterior funcional para mitigar impacto em produção.
  • Abra um um ticket na nossa Central de Ajuda contendo todas as informações e insumos da falha para que possamos apoiá-lo.