Melhores Práticas de Implementação do SDK

Segue abaixo uma lista de melhores práticas para implementação do SDK da Unico, a fim de dirimir problemas e ganhar tempo de implementação.

Utilize uma POC para facilitar sua implementação

A Unico fornece um conjunto de POC (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 com nosso time de atendimento através do portal de clientes.

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, além de ter agilidade em atualizações críticas.

Para mais detalhes pode-se consultar a política de atualizações das SDKs.

Identifique qual é a versão mais atualizada disponível para SDK

Importante garantir que realize sua atualização para versão mais recente disponível:

• Android: [lista de versões]
• IOS: [lista de versões]
• Flutter: [lista de versões]
• WEB: [lista de versões]

Evite atualizar a SDK e outros componentes/funcionalidades ao mesmo tempo

Sabemos que seu aplicativo faz uso de diversas outras bibliotecas e funcionalidades, muitas vezes sendo carregadas de forma simultânea à SDK da Unico. Como boa prática de atualização, evite realizar o processo de upgrade de nossa SDK ao mesmo tempo que atualiza alguma outra funcionalidade / biblioteca pois, 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.

Está com alguma dificuldade de atualização da SDK ? Podemos apoiá-lo

Caso esteja com dificuldade, abra um ticket no nosso portal de clientes com as seguintes informações (para agilizar a tratativa):

• Qual é a linguagem da SDK que você está tentando atualizar ?
• Caso seja mobile (Android ou IOs), trata-se de uma implementação nativa ou híbrida (informar detalhes)?
• Em caso de implementação JavaScript, qual o framework utilizado?
• Qual é a versão atual da SDK que você está tentando atualizar ? (não é necessário caso seja uma nova instalação)
• Qual é a nova versão que está sendo realizada a tentativa de instalação/atualização ?
• Por favor, informe qual API Key está sendo utilizada.
• A atualização consiste apenas no upgrade do SDK ou outros componentes / funcionalidades também estão sendo alterados/atualizados/modificados ? Em caso afirmativo, por favor descreva quais itens adicionais estão sendo modificados.
• Prover uma descrição dos passos executados e quais foram os resultados/erros.
• Por favor anexar evidências e insumos relacionados a falha/problema (arquivos de logs contendo trecho de erros/falhas, printscreens e/ou vídeos reproduzindo o problema)

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 da imagem obtida, que pode ser utilizado se quiser exibir 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, pois 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

Em resumo: nunca tente ler ou manipular o atributo Encrypted (JWT).

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. É muito importante que sua implementação utilize a mesma API Key no fluxo de captura e no fluxo de envio, pois evita erros de integração, facilita 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 quando 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 pois a SDK identifica como possível fraude e invalida a passagem quando enviada ao backend. Por isso, 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 identificado na atualização de novas versões (WEB)

Ao subir versões para o SDK WEB, caso tenha atualização também de arquivos resources, sempre excluir o arquivo antigo e inserir os novos na pasta Public, pois pode acontecer dos arquivos estarem com o mesmo nome e não serem 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, deve-se sempre utilizar o nosso plugin de flutter específico para este propósito. Reforçamos que não tentem implementar as versões nativas do nosso SDK (Android, IOS) através de bridges em aplicações flutter pois normalmente esta ação gera 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 do SDK possui 2 etapas até a captura da foto e geração do encrypted:

• a preparação da câmera e
• a abertura da câmera.

Na primeira etapa é preciso passar o tipo de câmera a ser utilizado e o bundle com as informações de API KEY, estando tudo correto a autenticação com o backend do SDK é realizada com sucesso. Na segunda etapa é feita a abertura da câmera, normalmente a partir de um clique de botão do usuário. A autenticação com o backend do SDK pode levar alguns segundos, então colocar essa etapa junto com a abertura de câmera no clique do botão que o usuário utiliza 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 será superior.

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. Abaixo alguns exemplos de como realizar:

Para o Flutter seguir com o comando:

• Remover 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) do SDK no contexto da captura. Ele pode ser retornado 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.
• 511 também pode ser retornado quando o SDK não localizar uma face na imagem 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 assim 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 do SDK vocêadicione às suas regras de ofuscação a configuração para o SDK Unico, caso contrário enfrentará problemas ao tentar buildar o projeto utilizando o SDK IOS, Android ou Flutter.

Abaixo os links para as configurações de ofuscação de cada OS: Android: Link documentação ofuscação Android IOS: Link documentação ofuscação IOS

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 tenha 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 no nosso portal de clientes contendo todas as informações e insumos da falha para que possamos apoiá-lo