Guia de integração

O Certiface SDK é uma solução modular para verificação de biometria facial e validação de documentos, criada para facilitar o processo de autenticação de usuários. Ele é construído em torno do núcleo OitiCore, que gerencia automaticamente dependências e fluxos de execução, garantindo uma integração simplificada e flexível.

Sua arquitetura permite que configure diferentes fluxos, com a possibilidade de customizar e capturar respostas específicas de cada solução através de interceptores.

Permissões de acesso

No Info.plist do projeto, adicione as descrições de uso de câmera (Privacy - Camera Usage Description) e de localização (Privacy - Location When In Use Usage Description).

Resumo das Permissões

Câmera: necessária para captura de imagem no processo de liveness e documento.
Localização: utilizada para fornecer ainda mais precisão no resultado da biometria.

Configuração do hub de soluções

Para utilizar todas os produtos presente no hub soluções do SDK é preciso configurar a classe HubManager.

Passo 1: Importação do SDK

Importe o módulo de OitiCore no arquivo onde será utilizada:

import OitiCore

Passo 2: Configuração das credenciais

Configure o objeto HubManagerUser com as seguintes informações:

Parâmetro	Descrição
ticket	Token para orchestração das soluções.
key	Token que fornece informações essenciais para execução das soluções.
environment	Ambiente de execução das soluções.
org	Especifica a organização ao qual o workflow de execução pertence.
branch	Especifica a ramificação da organização fornecida.

Exemplo de implementação

let user = HubManagerUser(
    ticket: "TICKET", 
    key: "KEY", 
    environment: .hml, 
    org: 100, 
    branch: 2000
)

Passo 3: Configuração do Callback

Para ser possível interpretar as respostas do SDK é necessário implementar o protocolo HubCallback que fornece os métodos ao qual o nosso framework utiliza para devolver os resultados ou problemas capturados durante a execução da jornada.

Métodos do protocolo

Método	Descrição
`onConnect()`	Informa quando a configuração da solução foi finalizada e marca o início da sua execução.
`onSuccess()`	Informa quando todas as soluções foram executadas com sucesso.
`onError(_:)`	Informa quando um erro foi capturado durante a orquestração das soluções.
`onCancel()`	Informa quando o usuário cancelou a jornada.

Exemplo de implementação

final class CallbackManager: HubCallback {
    
    func onConnect() { ... }
    
    func onSuccess() { ... }
    
    func onError(_ error: OitiError) { ... }
    
    func onCancel() { ... }
}

let callbackManager = CallbackManager()

Passo 4: Builder de configuração

A classe HubManagerBuilder é responsável por encapsular as informações necessárias para criação do objeto de HubManager.

Exemplo de implementação

let hubManager = HubManagerBuilder(
    user: user, 
    callback: callbackManager
).build()

Passo 5: Orquestração das soluções

A execução do HubManager é feita através do método assíncrono start() tanto em ambientes construídos em SwiftUI quanto em UIKit, respeitando algumas diferenças entre esses frameworks.

SwiftUI

Na execução em SwiftUI é necessário passar a referência de um objeto do tipo HubManagerLauncher para o método start(with:) como demonstrado no exemplo de código abaixo:

struct ExampleView: View {
    /* Launcher para execução do HubManager */
    private let launcher = HubManagerLauncher()
    
    var body: some View { ... }
    
    func startSolutions() async {
        /* Configuração das credenciais */
        let user = HubManagerUser(
            ticket: "TICKET",
            key: "KEY",
            environment: .hml,
            org: 100,
            branch: 2000
        )
        
        /* Configuração do callback */
        let callbackManager = CallbackManager()

        /* Builder de configuração */
        let hubManager = HubManagerBuilder(
            user: user,
            callback: callbackManager
        ).build()
        
        /* Início da orquestração das soluções */
        await hubManager.start(with: launcher)
    }
}

UIKit

Na execução em UIKit é necessário passar a referência de um objeto do tipo UIViewController para o método start(at:) como demonstrado no exemplo de código abaixo:

final class ExampleViewController: UIViewController {
    
    func startSolutions() async {
        /* Configuração das credenciais */
        let user = HubManagerUser(
            ticket: "TICKET",
            key: "KEY",
            environment: .hml,
            org: 100,
            branch: 2000
        )
        
        /* Configuração do callback */
        let callbackManager = CallbackManager()

        /* Builder de configuração */
        let hubManager = HubManagerBuilder(
            user: user,
            callback: callbackManager
        ).build()
        
        /* Início da orquestração das soluções */
        await hubManager.start(at: self)
    }
}

Passo 6 (opcional): Providers

Os Providers são componentes do SDK que representam cada uma das soluções de liveness e de validação de documentos. Eles podem ser configurados com Interceptors para capturar resultados detalhados, além de permitir a personalização da jornada, a partir dos builders de customização.

Configuração com interceptor

A configuração com interceptores permite que o SDK capture informações detalhadas sobre o resultado de cada provider. Esse método é útil para desenvolver um controle granular sobre o fluxo, além de facilitar a coleta de dados para análises posteriores.

import OitiCore
import OitiFacetec
import OitiLiveness2D

final class CallbackManager { ... }

// OitiFacetec
extension CallbackManager: FacetecInterceptor {
    
    func onIntercept(_ result: FacetecSuccessModel) { ... }
}

// OitiLiveness2D
extension CallbackManager: Liveness2DInterceptor {
    
    func onIntercept(_ result: Liveness2DSuccessModel) { ... }
}

// ----

let callbackManager = CallbackManager()
let hubManager = HubManagerBuilder(user: user, callback: callbackManager)
    .addProvider(FacetecProvider(interceptor: callbackManager))
    .addProvider(Liveness2DProvider(interceptor: callbackManager))
    .build()

Configuração com customização

import OitiCore
import OitiDocCore
import OitiFacetec
import OitiLiveness2D

struct ExampleView: View {
    private let launcher = HubManagerLauncher()
    
    var body: some View { ... }

    func startSolutions(with user: HubManagerUser, callback: CallbackManager) async {
        let hubManager = HubManagerBuilder(user: user, callback: callback)
            .addProvider(FacetecProvider(
                customization: FacetecCustomizationBuilder.builder(),
                interceptor: callbackManager
            ))
            .addProvider(Liveness2DProvider(
                customization: Liveness2DCustomizationBuilder.builder(),
                interceptor: callbackManager
            ))
            .addProvider(DocCoreProvider(
                customization: DocCoreCustomizationBuilder.builder()
            ))
        
        await hubManager.start(with: launcher)
    }
}

Builders de customização

Mais informações sobre os builders de customização estão presentes nos Guias de Customização de cada solução.