Introdução
Bem vindo à SDK iOS de Reconhecimento Facial da Zaig. Esta SDK realiza a captura de face e seu envio para a API de Face Recognition da Zaig. Você pode utilizar esta SDK para capturar através do seu aplicativo uma imagem do rosto de um cliente e referenciá-lo através de uma chave nos demais produtos do sistema Zaig.
Problemas?
Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!
Adoramos Feedback
Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!
Soluções híbridas
Além da integração nativa em Swift, nossos SDKs são compatíveis com: Flutter, Ionic Cordova, Capacitor, React Native entre outras. Atualmente nossos SDKs híbridos estão documentados em um repositório privado. Caso tenha interesse nestas integrações, entre em contato com nosso suporte para liberarmos acesso.
Importando a SDK
Remotamente
Iniciando a instalação
pod init
Nosso SDK pode ser importado utilizando CocoaPods.
| SDK | Versão atual |
|---|---|
| ZaigIosFaceRecon | pod 'ZaigIosFaceRecon', '~> 1.6.3' |
Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.
Adicionando a source no podfile
source 'https://github.com/ZaigCoding/iOS.git'
source 'https://cdn.cocoapods.org/'
O próximo passo é adicionar no arquivo podfile o source da Zaig.
Adicionando o pod no podfile
pod 'ZaigIosFaceRecon', '~> <version>'
Por fim, basta adicionar o nome do pod de acordo com o formato ao lado.
Exemplo de podfile
source 'https://github.com/ZaigCoding/iOS.git'
source 'https://cdn.cocoapods.org/'
target 'ExampleApp' do
use_frameworks!
pod 'ZaigIosFaceRecon', '~> 1.6.3'
end
post_install do |installer|
datadog_sdk = installer.pods_project.targets.detect {|e| e.name == 'DatadogSDK'}
datadog_sdk.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
Ao lado temos um exemplo completo da instalação.
Instalando as dependências
pod install
Por fim, execute o comando pod install para baixar e instalar as dependências.
Permissões Necessárias
Para que a SDK possa acessar os recursos do dispositivo para coletar a selfie do usuário, é necessário que sejam solicitadas permissões ao usuário.
No arquivo info.plist, adicione as permissões abaixo:
| Permissão | Motivo |
|---|---|
| Privacy - Camera Usage Description | Acesso à câmera para capturar a selfie do usuário. |
Iniciando a SDK
import ZaigIosFaceRecognition
class ViewController: UIViewController, ZaigIosFaceRecognitionControllerDelegate {
var zaigFaceRecognitionConfiguration : ZaigIosFaceRecognitionConfiguration?
override func viewDidLoad() {
super.viewDidLoad()
self.setupFaceRecognition()
}
func setupFaceRecognition() -> Void {
// The environment can be 'Sandbox' ou 'Production'
let environment = ZaigIosFaceRecognitionEnvironment.Sandbox
// MobileToken is the key sent to you by Zaig. Each environment requires a different MobileToken.
let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_ZAIG"
self.faceRecognitionConfig = ZaigIosFaceRecognitionConfiguration(environment: environment,
mobileToken: mobileToken,
sessionId: "UNIQUE_SESSION_ID",
backgroundColor: "#000000",
fontColor: "#FFFFFF",
fontFamily: .open_sans,
showIntroductionScreens: true,
activeFaceLiveness: true,
audioConfiguration: AudioConfiguration.Enable,
logLevel: .debug
)
}
// Event where you intend to call Zaig FaceRecognition View Controller - on this example, when the user press 'next' button
@IBAction func pressNext(_ sender: Any) {
let zaigFaceRecognitionController = ZaigIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
zaigFaceRecognitionViewController.delegate = self
let zaigFaceRecognitionViewController = zaigFaceRecognitionController.getViewController()
present(zaigFaceRecognitionViewController, animated: true, completion: nil)
}
// Do something if Zaig FaceRecognition's SDK successfully collected document picture
func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFinishWithResults results: ZaigIosFaceRecognitionControllerResponse) {
}
// Do something if Zaig FaceRecognition's SDK found any error when collecting document picture
func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFailWithError error: ZaigIosFaceRecognitionControllerError) {
}
// Do something if the user canceled the picture collection on any steps
func zaigIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: ZaigIosFaceRecognitionController) {
}
}
Para incorporar a SDK ao seu aplicativo você deve iniciar realizar a configuração do seu aplicativo de captura personalizado através da classe ZaigIosFaceRecognitionConfiguration e depois instanciar o ViewController ZaigIosFaceRecognitionController passando como argumento as configurações personalizadas.
Para iniciar o processo de análise de face, basta chamar a função present para chamar o ViewController da Zaig que realizará a coleta da selfie.
Importante implementar o Delegate responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.
Ao lado temos um exemplo completo da implementação.
Mobile Token
Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br.
Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas da SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.
ZaigIosFaceRecognitionConfiguration
let visualConfiguration = VisualConfiguration()
visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200)
let textConfiguration = TextConfiguration()
textConfiguration.setCustomText(on: .onboardingTitle, text: "Para tirar uma boa foto:")
textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local iluminado")
textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire adereços e mostre bem o rosto")
textConfiguration.setCustomText(on: .onboardingThirdLabel, text: "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura")
let faceRecognitionConfig = ZaigIosFaceRecognitionConfiguration(environment: ZaigIosFaceRecognitionEnvironment.Sandbox,
mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a",
sessionId: "7d8c6f9a-f222-450d-9501-a07c68eb2388",
documentSteps: documentSteps,
backgroundColor: "#C9CCD3",
fontColor: "#337DFF",
fontFamily: .open_sans,
showIntroductionScreens: true,
showSuccessScreen: false,
activeFaceLiveness: true,
audioConfiguration: AudioConfiguration.Enable,
logLevel: .debug
)
faceRecognitionConfig.setVisualConfiguration(visualConfiguration: visualConfiguration)
faceRecognitionConfig.setTextConfiguration(textConfiguration: textConfiguration)
A classe ZaigIosFaceRecognitionConfiguration é utilizada para que você possa configurar ambiente, credenciais, aspectos visuais e textuais ou seja, todas as configurações necessárias para personalização e funcionamento da SDK.
Na tabela abaixo você encontra o detalhe de todos os argumentos que devem ser utilizados na sua instanciação:
| nome | tipo | descrição |
|---|---|---|
| environment | ZaigIosFaceRecognitionEnvironment | (obrigatório) Enumerador que descreve o ambiente. |
| sessionId | string | (opcional) ID único usado para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. |
| mobileToken | string | (obrigatório) Token enviado pela Zaig para autenticação da SDK. |
| backgroundColor | string | (opcional) Hexadecimal da cor de fundo das telas. Caso não seja informada o padrão é #FFFFFF. |
| fontColor | string | (opcional) Hexadecimal da cor da fonte. Caso não seja informada o padrão é #000000. |
| fontFamily | FontFamily | (opcional) Familia da fonte. Caso não seja informada o padrão é .open_sans. Fontes disponíveis: .open_sans, .futura, .verdana, .trebuchetms, .tamilsangammn e .system_font. |
| showIntroductionScreens | booleano | (opcional) Flag que indica se as telas de introdução, com instruções de como a foto deve ser capturada, devem ser mostradas. Caso não seja informada o padrão é true. |
| showSuccessScreen | booleano | (opcional) Flag que indica se a tela de sucesso, com a mensagem de sucesso na captura, deve ser mostrada. Caso não seja informada o padrão é true. |
| activeFaceLiveness | booleano | (opcional) Indica se a SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa. Caso não seja informada o padrão é false. |
| audioConfiguration | AudioConfiguration | (opcional) Indica se a SDK deve ou não executar áudios de indicação para o usuário. As configurações aceitas são: Enable que sempre executará os áudios de indicação, Disable que nunca executará estes áudios e Accessibility que executa os áudios caso o dispositivo do usuário possua configurações de acessibilidade ativadas. |
| logLevel | LogLevel | (opcional) . Utilizado para customizar o nível de verbosidade dos logs da SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. Caso não seja informada o padrão é LogLevel.debug. |
Na tabela abaixo você encontra todos os métodos aceitos pela instância para configuração:
| método | argumentos | descrição |
|---|---|---|
| setVisualConfiguration | visualConfiguration : VisualConfiguration | (opcional) Classe que permite a modificação das imagens exibidas durante a execução da SDK; |
| setTextConfiguration | textConfiguration : TextConfiguration | (opcional) Classe que permite a modificação dos textos exibidos durante a execução da SDK; |
| setDocumentNumber | Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres. | Não. |
| setValidation | Utilizado para definir se a SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar obrigatoriamente false. Esta função depende necessita do método setDocumentNumber preenchido. | Não. O padrão é false. |
VisualConfiguration
A classe VisualConfiguration é utilizada para configurar os ícones e imagens que aparecem para o usuário durante a execução da SDK.
Esta classe apresenta os seguintes métodos de configuração da instância:
| método | argumentos | descrição |
|---|---|---|
| setOnboarding | onboardingFilePath: String, onboardingWidth: Int | (opcional) Endereço local do asset da imagem que será apresentado na tela de Onboarding do usuário durante a execução da SDK; Tamanho desejado de exibição da imagem; |
TextConfiguration
A classe TextConfiguration é utilizada para configurar os textos das labels que aparecem para o usuário durante a execução da SDK.
Esta classe apresenta os seguintes métodos de configuração da instância:
| método | argumentos | descrição |
|---|---|---|
| setCustomText | on: Label, text: String | (opcional) Texto que será utilizado para substituir o texto padrão da tela de introdução da SKD; Labels disponíveis: .onboardingTitle, .onboardingFirstLabel, .onboardingSecondLabel e .onboardingThirdLabel |
Enumeradores
Os valores possíveis do enumerador ZaigIosFaceRecognitionEnvironment podem ser:
ZaigIosFaceRecognitionEnvironment.Sandbox- Utilizado para uso da SDK no ambiente de sandbox da Zaig.ZaigIosFaceRecognitionEnvironment.Production- Utilizado para uso da SDK no ambiente de produção da Zaig.
Coletando os Retornos
class ViewController: UIViewController, ZaigIosFaceRecognitionControllerDelegate {
// Do something if Zaig FaceRecognition's SDK succesfully collected document picture
func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFinishWithResults response: ZaigIosFaceRecognitionControllerResponse) {
}
// Do something if Zaig FaceRecognition's SDK found any error when collecting document picture
func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFailWithError error: ZaigIosFaceRecognitionControllerError) {
}
// Do something if the user canceled the picture collection on any steps
func zaigIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: ZaigIosFaceRecognitionController) {
}
}
Para obter as respostas da SDK , você deve implementar o delegate ZaigIosFaceRecognitionControllerDelegate em seu controller, conforme exemplo ao lado.
ZaigIosFaceRecognitionControllerResponse
A classe ZaigIosFaceRecognitionControllerResponse é utilizada para que você possa receber a resposta da SDK da Zaig.
Na tabela abaixo você encontra o detalhe de todas as propriedades desta classe:
| nome | tipo | descrição |
|---|---|---|
| FaceRecognitionKey | string | Identificador único da foto do rosto na Zaig. Você deve armazenar esse identificador para enviar na API da Zaig que realizará a validação (ex.: API de Onboarding) |
ZaigIosFaceRecognitionControllerError
A classe ZaigIosFaceRecognitionControllerError é acionada no caso de algum erro que leve ao encerramento da SDK. Quando isso ocorrer, a Zaig retornará uma subclasse que terá um nome correspondente ao erro que levou ao encerramento da SDK, conforme tabela abaixo:
| classe | descrição |
|---|---|
| InvalidMobileToken | MobileToken enviado nas configurações é inválido. |
| MissingPermission | Alguma das permissões necessárias para a validação não foi suficiente. |
| NetworkFailure | O usuário perdeu a conexão com a internet durante a validação. |
| ServerFailure | O servidor da Zaig devolveu alguma resposta de erro para a SDK. |
| MissingStorage | Não há espaço de armazenamento suficiente no dispositivo do usuário para que seja realizada a coleta da imagem. |
| LowImageQuality | Por algum motivo a qualidade da imagem coletada não foi o suficiente para realização da validação. |
Para mapear qual a subclasse, e portanto, qual o motivo do erro, utilize o método isKindOfClass() do swift.