Captura de Selfie

Este guia foi elaborado para ajudá-lo a implementar o SDK iOS de forma rápida e fácil. São disponibilizados conceitos básicos, exemplos de implementação dos SDKs e também de como interagir com as APIs REST do motor biométrico.

Através deste guia, é possivel:

• Implementar a abertura da câmera e captura de imagens;
• Manipular os dados de retorno;
• Utilizar o retorno do SDK com as APIs do motor biométrico.

Antes de começar, certifique-se que seguiu o passo-a-passo para instalação e importação do SDK neste guia.

RECURSOS DISPONÍVEIS

O SDK iOS oferece um componente para captura de selfie contendo uma silhueta que ajuda o usuário a se posicionar de forma correta para a foto. A captura da selfie pode ser feita de duas formas, sendo elas:

CAPTURA MANUAL

Neste tipo de experiência existe um frame de captura para auxiliar o usuário a posicionar sua face corretamente. Após se posicionar corretamente, o usuário deve clicar em um botão para capturar a imagem.

O SDK não efetua nenhum tipo de validação do que está sendo capturado. Caso a imagem capturada não possua uma face biométricamente válida, o encrypted é recusado pelas APIs do motor de biometria.

CAPTURA AUTOMÁTICA

Neste tipo de experiência, a face do usuário é identificada automaticamente através de algoritmos de visão computacional e ele é auxiliado para que se posicione de forma correta dentro da área de captura. Após se posicionar corretamente, a imagem é capturada de forma automática.

Por ajudar o usuário a enquadrar sua face na área de captura, esta opção pode diminuir problemas ao enviar o encrypted às APIs do motor biométrico.

LIVENESS COM INTERAÇÃO

Neste tipo de experiência o usuário é instruído a realizar alguns movimentos simples durante a captura, que são acompanhados por algoritmos de visão computacional com o intuito de garantir que ele está tirando foto naquele momento.

Por exigir a movimentação do usuário, este tipo de captura possui uma camada extra de segurança contra fraudes. Tal como na Captura Automática a imagem é capturada sem a necessidade do usuário pressionar um botão. Desta forma existe uma tendência a diminuir problemas ao enviar o encrypted às APIs do backend do motor biométrico.

Ativação do Liveness

A ativação da funcionalidade pode ser verificada no portal do cliente, como explicado neste artigo.

IMPLEMENTAÇÃO

Seguindo este passo-a-passo, você tem todo o potencial do SDK embarcado em sua aplicação iOS.

1. INICIALIZAR O SDK

   Para iniciar com SDK iOS do Unico Check, importe o SDK e implemente a interface AcessoBioManagerDelegate dentro da ViewController que deseja utilizar.

   A implementação dessa classe é bem simples e pode ser feita com poucas linhas de código. Tudo que precisa fazer é instanciar o builder informando o contexto e ambiente em questão e sobrescrever os métodos de callback com as lógicas de negócio de sua aplicação:

   Objective-C

   .m:
   #import "ViewController.h"
   #import <AcessoBio/AcessoBio.h>
   
   @implementation ViewController: UIViewController
   - (void)viewDidLoad {
       [super viewDidLoad];  
       unicoCheck = [[AcessoBioManager alloc]initWithViewController:self];
   }
   
   - (void)onErrorAcessoBioManager:(ErrorBio *)error {
     // your code
   }
   
   - (void)onSystemChangedTypeCameraTimeoutFaceInference {
     // your code
   }
   
   - (void)onSystemClosedCameraTimeoutSession {
     // your code
   }
   
   - (void)onUserClosedCameraManually {
     // your code
   }
   @end

   Swift

   import UIKit
   import AcessoBio
   
   class ViewController: UIViewController, AcessoBioManagerDelegate {
     var unicoCheck: AcessoBioManager!
   
     override func viewDidLoad() {
       super.viewDidLoad()      
       unicoCheck = AcessoBioManager(viewController: self)
     }
   
     func onErrorAcessoBioManager(_ error: ErrorBio!) {
         // your code
     }
   
     func onUserClosedCameraManually() {
         // your code
     }
   
     func onSystemClosedCameraTimeoutSession() {
         // your code
     }
   
     func onSystemChangedTypeCameraTimeoutFaceInference() {
         // your code 
     }
   }

   CONFIGURAÇÃO DE AMBIENTES

   Configure o ambiente que será utilizado na execução da SDK. Utilize o enumerado Environment que contém os seguintes enumerados:

   PROD: para ambiente de Produção

   UAT: para ambiente de Homologação

   Veja como implementar no exemplo abaixo:

   objectivec

       [unicoCheck setEnvironment:UAT];

   swift

       unicoCheck.setEnvironment(.UAT)

   IMPLEMENTAR AS FUNÇÕES DE CALLBACK

   Note que, conforme o exemplo anterior, o trabalho de implementação da classe UnicoListener é, em grande parte, a configuração dos métodos de callback. Cada método será chamado em uma situação específica de retorno do SDK.

   Basta sobrescrever os métodos exemplificados no passo anterior com as lógicas de negócio de sua aplicação:

   Método onErrorAcessoBioManager(_ error: ErrorBio!)

   Este método é invocado quando qualquer erro de implementação ocorrer ao utilizar algum dos métodos, como por exemplo, ao informar um tipo de documento incorreto para a funcionalidade de captura de documentos.

   Ao ser invocado, o método receberá um parâmetro do tipo ErrorBio que contem detalhes do erro. Saiba mais sobre o tipo ErrorBio no artigo de Referências deste SDK.

   Método onUserClosedCameraManually()

   Este método é invocado quando o usuário fechar a câmera de forma manual, como por exemplo, ao clicar no botão "Voltar".

   Método onSystemClosedCameraTimeoutSession()

   Este método é invocado assim que o tempo máximo de sessão for atingido (sem capturar nenhuma imagem).

   Método onSystemChangedTypeCameraTimeoutFaceInference()

   Este método é invocado assim que o tempo máximo para detecção da face de um usuário for atingido (sem ter nada detectado). Neste caso, o modo de câmera é alterado automaticamente para o modo manual (sem o smart frame).

   Atenção

   Todos os métodos acima devem ser criados da forma indicada em seu projeto (mesmo que sem nenhuma lógica). Caso contrário, o projeto não compila com sucesso.

2. CONFIGURAR O MODO DA CÂMERA

   Como explicado anteriormente, existem três modos de câmeras de captura disponíveis. Se não estiver utilizando o modo Liveness com interação, nesta etapa você pode escolher entre o modo de captura Manual ou Automático.

   Dica

   Caso você esteja utilizando o modo Liveness com interação, a configuração do tipo de câmera é irrelevante, pois este modo oferece uma experiência pré-definida que não pode ser alterada.

   No entanto, é recomendado que você configure um tipo de câmera em seu builder (como descrito neste passo), pois caso você desabilite o modo Liveness com interação em seu portal do cliente (e gere um novo JSON), você não precisa alterar seu código.

   O SDK tem configurado e habilitado por padrão o enquadramento inteligente e a captura automática. Para utilizar a câmera em modo normal, desabilite ambas funcionalidades através dos métodos setAutoCapture e setSmartFrame.

   Os exemplos a seguir demonstram como você pode configurar cada um dos modos de câmera a partir da ação de um botão em sua UI:

   Modo inteligente (Captura automática - Smart Camera)

   Por padrão, o SDK possui o enquadramento inteligente e a captura automática habilitados. Caso utilize este modo de câmera, não é necessário alterar nenhuma configuração.

   Caso as configurações da câmera tenham sido alteradas previamente em seu App, é possível restaurá-las através dos métodos setAutoCapture e setSmartFrame:

   Objective-C

   .m:
   - (IBAction)configureSmartCamera:(UIButton *)sender {
      // Objeto unicoCheck da classe AcessoBioManager
      [unicoCheck setSmartFrame:true];
      [unicoCheck setAutoCapture:true];
   }

   Swift

   @IBAction func configureSmartCamera(_ sender: Any) {
       // Objeto unicoCheck da classe AcessoBioManager
       unicoCheck.setSmartFrame(true)
       unicoCheck.setAutoCapture(true)    
   }
   Atenção

   Não é possível implementar o método setAutoCapture(true) com o método setSmartFrame(false), ou seja, não é possível manter a captura automática sem o Smart Frame, pois é ele quem realiza o enquadramento inteligênte.

   Modo manual

   Por padrão, o SDK possui o enquadramento inteligente e a captura automática habilitados. Para utilizar o modo manual ambas as configurações relacionadas a Smart Camera devem ser desligadas através dos métodos setAutoCapture e setSmartFrame:

   Objective-C

   .m:
   - (IBAction)configureSmartCamera:(UIButton *)sender {
       // Objeto unicoCheck da classe AcessoBioManager
       [unicoCheck setSmartFrame:false];
       [unicoCheck setAutoCapture:false];
   }

   Swift

   @IBAction func configureSmartCamera(_ sender: Any) {
       // Objeto unicoCheck da classe AcessoBioManager
       unicoCheck.setSmartFrame(false)
       unicoCheck.setAutoCapture(false)    
   }
   Dica - SmartFrame

   Mesmo em modo manual é possível utilizar o Smart Frame. Neste caso, a silhueta é exibida para identificar o enquadramento para então habilitar o botão. Para isto, basta configurar setAutoCapture(autoCapture: false) e setSmartFrame(smartFrame: true)

3. IMPLEMENTAR DELEGATES PARA EVENTOS DA CÂMERA

   O método de abertura da câmera precisa saber o que fazer ao conseguir capturar uma imagem com sucesso ou ao ter algum erro no processo. É informado "o que fazer" ao método de abertura da câmera através da configuração de delegates que são chamados em situações de sucesso ou erro.

   Através da configuração dos delegates, você pode especificar o que acontece em seu App em situações de erro (método onErrorSelfie) ou sucesso (método onSuccessSelfie) na captura de imagens.

   Para a configuração dos delegates, você deve implementar as interfaces SelfieCameraDelegate e AcessoBioSelfieDelegate:

   Objective-C

   .h:
   #import <UIKit/UIKit.h>
   #import <AcessoBio/AcessoBio.h>
   #import "SelfieCameraDelegate.h"
   
   @interface ViewController: UIViewController <AcessoBioManagerDelegate, SelfieCameraDelegate,
      AcessoBioSelfieDelegate> {
     AcessoBioManager *unicoCheck;
     // Your code from previous and next steps here
   }

   Swift

   import UIKit
   import AcessoBio
   
   class ViewController: UIViewController, AcessoBioManagerDelegate,
                         SelfieCameraDelegate, AcessoBioSelfieDelegate {    
     //Your code from previous and next steps here
   }

   Método onSuccessSelfie

   Ao efetuar uma captura de imagem com sucesso, este método é invocado e retorna um objeto do tipo SelfieResult que é utilizado posteriormente na chamada das APIs REST.

   Objective-C

   - (void)onSuccessSelfie:(SelfieResult *)result {
       NSLog(@"%@", result.base64);
   } 

   Swift

   func onSuccessSelfie(_ result: AcessoBio.SelfieResult!) {
       // Your code
    }

   O objeto ResultCamera retorna 2 atributos: Base64 e Encrypted:

   • O atributo Base64 pode ser utilizado se quiser exibir uma prévia da imagem em seu app;
   • O atributo Encrypted deve ser enviado na chamada das APIs REST do unico | check.
   Conversão do base64 para Bitmap

   Caso queira converter o base64 para bitmap, a maneira padrão não funciona para o iOS. É necessário realizar o split a partir da vírgula(,) para que funcione. Caso queira saber mais, leia o seguinte artigo:

   How to convert a Base64 string into a Bitmap image to show it in a ImageView?

   Alerta

   O atributo Encrypted é destinado estritamente ao envio da imagem através das APIs da Unico. Não se deve abrir e 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.

   Alerta

   O base64 pode sofrer variações de tamanho de acordo com diversas variáveis, dentre elas, a qualidade dos aparelhos e das fotos geradas pelos mesmos e regras de negócio da Unico. Para não encontrar problemas em sua aplicação, não limite em sua lógica de programação ou sua infraestrutura o tamanho da string gerada pela SDK para o base64.

   Método onErrorSelfie

   Ao ocorrer algum erro na captura de imagem, este método é invocado e retorna um objeto do tipo ErrorBio.

   Objective-C

   - (void)onErrorSelfie:(ErrorBio *)errorBio {
     // Your code
   }

   Swift

   func onErrorSelfie(_ errorBio: ErrorBio!) {
     // Your code
    }
   Saiba mais

   Saiba mais sobre o tipo ErrorBio na página de Referências deste SDK.

4. PERSONALIZAR O PROCESSO DE CAPTURA

   Esta é uma etapa opcional, porém muito recomendada para que o processo de captura tenha a identidade visual da sua empresa.

   É possível customizar alguns objetos do frame de acordo com o modo de câmera utilizado, através do método setTheme().

   Entenda um pouco mais sobre o método setTheme(), exemplos de utilização e o que pode ser customizado na página de Referências deste SDK.

5. PERSONALIZAR O IDIOMA

   É possível configurar a experiência das mensagens informativas dos frames de captura alterando seu idioma. Utilize o enumerado LocaleTypes que contém os seguintes valores:

   Observações:

   1- Este recurso só está disponível para câmera com Liveness
   2- Pode ser necessário uma ativação remota para ser utilizado, caso deseje usar, por favor acionar o CSM da conta.
   3- Caso não seja configurado, por padrão o SDK iOS utiliza o Português como idioma principal.
   

   LocaleTypes.PT_BR: para Português(Brasil)
   LocaleTypes.ES_MX: para Espanhol(México)
   LocaleTypes.ES_ES: para Espanhol(Espanha)
   LocaleTypes.EN_US: para Inglês(EUA)
   

   Veja como implementar no exemplo abaixo:

   Objective-C

   [unicoCheck setLocale:EN_US];

   Swift

   unicoCheck.setLocale(.EN_US)

6. CONFIGURAÇÃO DE AMBIENTES

   Configuração padrão

   Caso não seja configurado, a SDK usa o ambiente configurado em através do arquivo de configuração (getHostKey). Caso getHostKey não esteja sendo usado, um erro é retornado.

   É possível configurar o ambiente que será utilizado na execução da SDK. Utilize o enumerado EnvironmentEnum que contém os seguintes enumerados:

   EnvironmentEnum.PROD: para ambiente de Produção

   EnvironmentEnum.UAT: para ambiente de Homologação

   Veja como implementar no exemplo abaixo:

   Objective-C

   [unicoCheck setEnvironment:PROD];

   Swift

   unicoCheck.setEnvironment(.PROD)

7. COMO PERSONALIZAR O LIVENESS INTERATIVO COM SEU LOGOTIPO

   Para uma experiência de autenticação mais associada a sua marca, você pode inserir e personalizar o logotipo em tempo real.

   Adicione em seu projeto uma imagem com o seguinte nome unico_custom_footer_logo.

   Observação

   O do arquivo precisa estar com nome correto. Caso contrário a implementação não funciona.

   Ao rodar o projeto novamente seu logotipo deve aparecer no rodapé da tela como mostrado a seguir:

   

8. PREPARAR E ABRIR CÂMERA

   Para seguir com a abertura da câmera, primeiro deve-se prepará-la utilizando o método prepareSelfieCamera. Este método recebe como parâmetro a implementação da classe SelfieCameraDelegate e o JSON com as credenciais, gerado nessa etapa.

   Objective-C

   .h:
   #import <UIKit/UIKit.h>
   #import <AcessoBio/AcessoBio.h>
   #import "SelfieCameraDelegate.h"
   
   @interface ViewController: UIViewController <AcessoBioManagerDelegate,
   SelfieCameraDelegate, AcessoBioSelfieDelegate> {
       AcessoBioManager *unicoCheck;
   }
   
   .m:
   - (IBAction)openCamera:(UIButton *)sender {
       [[unicoCheck build] prepareSelfieCamera:self config:[YourUnicoConfigClass new]];
   }

   Swift

   import UIKit
   import AcessoBio
   
   class ViewController: UIViewController, AcessoBioManagerDelegate,
     SelfieCameraDelegate, AcessoBioSelfieDelegate {
       @IBAction func openCamera(_ sender: Any) {
           unicoCheck.build().prepareSelfieCamera(self, config: YourUnicoConfigClass())
       }
   }

   Quando a câmera estiver preparada, o evento onCameraReady é disparado e recebe como parâmetro um objeto do tipo AcessoBioCameraOpenerDelegate.

   Você deve sobrescrever este método, efetuando a abertura da câmera com o objeto recebido através do método open():

   Objective-C

   - (void)onCameraReady:(id)cameraOpener {
       [cameraOpener open:self];
   }
   
   - (void)onCameraFailed:(ErrorPrepare *)message {
       // Your code
   }

   Swift

   func onCameraReady(_ cameraOpener: AcessoBioCameraOpenerDelegate!) {
       cameraOpener.open(self)
    }
    
   func onCameraFailed(_ message: ErrorPrepare!) {
       // Your code
    }
   Saiba mais

   O tipo ErrorPrepare é uma extensão de ErrorBio contendo assim todas as suas propriedades. Saiba mais sobre o tipo ErrorBio na página de Referências deste SDK.

   Caso ocorra algum erro ao preparar a câmera, o evento onCameraFailed é disparado. Você devem implementar este método aplicando as regras de negócio de seu App.

9. CHAMAR AS APIS

   A captura das imagens é apenas a primeira parte da jornada. Após capturar a imagem, é necessário enviar o Encrypted gerado para as APIs, selecionando um dos fluxos disponíveis detalhados em Fluxos.

   Atenção

   Por motivos de segurança, o intervalo entre a geração do Encrypted e o envio via um dos fluxos disponíveis deve ser de até no máximo 10 minutos. Envios feitos além deste período serão rejeitados automaticamente pela API.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.