Guia de uso SDK BioTrust - iOS

Este guia fornece instruções detalhadas para integrar o BiometricFaceValidator SDK em aplicações iOS.

:::tip Pré-requisitos

iOS 13.0 ou superior
Xcode 12.0 ou superior
Dispositivo físico (não funciona no Simulador)
Câmera frontal funcional :::

:::tip Exemplo

Faça download da aplicação exemplo do SDK BioTrust
https://github.com/biotrust-io/BioTrust-Example-IOS :::

Instalação

Swift Package Manager

O SDK é distribuído como um XCFramework binário via Swift Package Manager.

No Xcode, vá em File → Add Package Dependencies… e informe a URL do repositório:

URL do pacote
https://github.com/biotrust-io/BioTrust-SDK-IOS-Release

Ou declare no seu Package.swift:

Package.swift
dependencies: [
    .package(url: "https://github.com/biotrust-io/BioTrust-SDK-IOS-Release", from: "1.0.0")
],
targets: [
    .target(
        name: "SeuApp",
        dependencies: [
            .product(name: "BioTrust", package: "BioTrust-SDK-IOS-Release")
        ]
    )
]

No código, importe o módulo:

import BiometricFaceValidator

Permissões

Adicione no Info.plist:

Info.plist
<key>NSCameraUsageDescription</key>
<string>Este app precisa de acesso á câmera para validação biométrica facial.</string>

Configuração Básica

Inicialização do Framework

Antes de usar qualquer funcionalidade, inicialize o framework:

AppDelegate.swift
import BiometricFaceValidator

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BiometricFaceValidatorFramework.initializeFramework()
    return true
}

Criando a Configuração

O FaceBiometricConfig é criado usando o padrão Builder:

Configuração Básica
let config = FaceBiometricConfig.Builder()
    .setUuid("seu-uuid-aqui")
    .setApiUrl("https://api.biotrust.io")
    .setValidationMode(.livenessOnly)
    
do {
    let builtConfig = try config.build()
    // Usar builtConfig
} catch {
    print("Erro ao criar configuração: \(error)")
}

Parâmetros de Configuração

Parâmetros Obrigatórios

Parâmetro	Tipo	Descrição
`setUuid()`	`String`	Identificador único do usuário
`setApiUrl()`	`String`	URL da API de validação
`setValidationMode()`	`ValidationMode`	Modo de validação

Parâmetros Opcionais

Parâmetro	Tipo	Padrão	Descrição
`setChallengeCount()`	`Int`	`3`	Número de desafios (1-5)
`setRequireAllChallenges()`	`Bool`	`true`	Se todos os desafios são obrigatórios
`setTimeout()`	`Int`	`30000`	Timeout em milissegundos
`setEnableSoundFeedback()`	`Bool`	`true`	Habilitar feedback sonoro
`setEnableHapticFeedback()`	`Bool`	`true`	Habilitar feedback tátil
`setLocale()`	`String`	`nil`	Idioma ("en", "pt-BR", "es-ES")
`setThemeMode()`	`String`	`nil`	Tema ("light", "dark", "system")
`setCornerImage()`	`UIImage`	`nil`	Imagem personalizada no canto
`setCornerImagePosition()`	`BrandPosition`	`.bottomLeft`	Posição da imagem
`setDocumentInfo()`	`DocumentInfo`	`nil`	Informações do documento (obrigatório para `.livenessWithDocument`)

Modos de Validação

ValidationMode.swift
public enum ValidationMode {
    case livenessOnly                                              // Apenas prova de vida
    case livenessWithDocument                                     // Prova de vida + CPF
    case faceMatch(requireChallenges: Bool)                       // Prova de vida + busca 1:N
    case faceMatchExact(documentNumber: String, requireChallenges: Bool) // Conferência 1:1
}

Posições da Imagem

BrandPosition.swift
public enum BrandPosition: String {
    case bottomLeft = "bottom_left"
    case bottomRight = "bottom_right"
    case topLeft = "top_left"
    case topRight = "top_right"
}

Informações do Documento

Para validação com documento, crie um DocumentInfo:

DocumentInfo.example
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "dd/MM/yyyy"
let birthDate = dateFormatter.date(from: "01/01/1990")!

let documentInfo = DocumentInfo(
    cpf: "12345678901",
    birthDate: birthDate
)

Implementação

Criando o Launcher

ViewController.swift
import BiometricFaceValidator

class ViewController: UIViewController {
    private var launcher: BiometricValidationLauncher?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        BiometricFaceValidatorFramework.initializeFramework()
    }
}

Implementando os Callbacks

Os callbacks devem implementar o protocolo ValidationResultCallback:

MyValidationCallback.swift
class MyValidationCallback: BiometricValidationLauncher.ValidationResultCallback {
    
    // Chamado quando a validação de vivacidade é bem-sucedida
    func onValidationSuccess(
        message: String, 
        livenessConfidence: Float, 
        faceImage: UIImage?
    ) {
        print("Validação bem-sucedida: \(message)")
        print("Confiança de vivacidade: \(livenessConfidence)")
        
        if let image = faceImage {
            print("Imagem capturada: \(image.size)")
        }
    }
    
    // Chamado quando a validação falha
    func onValidationFailed(errorMessage: String) {
        print("Validação falhou: \(errorMessage)")
    }
    
    // Chamado quando ocorre um erro durante a validação
    func onValidationError(errorMessage: String) {
        print("Erro durante validação: \(errorMessage)")
    }
    
    // Chamado quando a validação com documento é concluída
    func onDocumentValidationComplete(result: ValidationResult) {
        if result.getIsSuccess() {
            print("Validação com documento bem-sucedida!")
            
            // Obter informações do documento
            if let docResult = result.getDocumentResult() {
                print("Nome: \(docResult.getFullName() ?? "N/A")")
                print("CPF: \(docResult.getCpf() ?? "N/A")")
                print("Data Nascimento: \(docResult.getBirthDate() ?? "N/A")")
                print("Similaridade: \(docResult.getSimilarityPercentage())%")
                print("Disponível: \(docResult.getIsAvailable())")
                print("Probabilidade: \(docResult.getProbability() ?? "N/A")")
            }
            
            // Confiança de vivacidade
            print("Confiança de vivacidade: \(result.getLivenessConfidence())")
            
            // Imagem capturada
            if let faceImage = result.getFaceImage() {
                print("Imagem capturada: \(faceImage.size)")
            }
        } else {
            print("Validação com documento falhou: \(result.getMessage())")
        }
    }
}

Iniciando a Validação

Validação de Vivacidade Apenas

Liveness Validation
func startLivenessValidation() {
    // Criar configuração
    let config = FaceBiometricConfig.Builder()
        .setUuid("seu-uuid-aqui")
        .setApiUrl("https://api.biotrust.io")
        .setValidationMode(.livenessOnly)
        .setLocale("pt-BR")
        .setChallengeCount(3)
    
    do {
        let builtConfig = try config.build()
        
        // Criar callback
        let callback = MyValidationCallback()
        
        // Criar launcher
        launcher = BiometricValidationLauncher(
            viewController: self,
            callback: callback,
            config: builtConfig
        )
        
        // Iniciar validação
        launcher?.launch(from: self)
        
    } catch {
        print("Erro ao criar configuração: \(error.localizedDescription)")
    }
}

Validação com Documento

Document Validation
func startDocumentValidation() {
    // Criar informações do documento
    let dateFormatter = DateFormatter()
    dateFormatter.dateFormat = "dd/MM/yyyy"
    let birthDate = dateFormatter.date(from: "01/01/1990")!
    
    let documentInfo = DocumentInfo(
        cpf: "12345678901",
        birthDate: birthDate
    )
    
    // Criar configuração
    let config = FaceBiometricConfig.Builder()
        .setUuid("seu-uuid-aqui")
        .setApiUrl("https://api.biotrust.io")
        .setValidationMode(.livenessWithDocument)
        .setDocumentInfo(documentInfo)
        .setLocale("pt-BR")
        .setChallengeCount(3)
    
    do {
        let builtConfig = try config.build()
        
        // Criar callback
        let callback = MyValidationCallback()
        
        // Criar launcher
        launcher = BiometricValidationLauncher(
            viewController: self,
            callback: callback,
            config: builtConfig
        )
        
        // Iniciar validação
        launcher?.launch(from: self)
        
    } catch {
        print("Erro ao criar configuração: \(error.localizedDescription)")
    }
}

FaceMatch (Reconhecimento 1:N)

Além da prova de vida, o SDK identifica quem é a pessoa comparando o rosto com a sua base cadastrada.

Buscar na base (1:N)

Roda a prova de vida e procura o rosto entre todos os cadastros.

FaceMatch — busca 1:N
let config = try FaceBiometricConfig.Builder()
    .setUuid("seu-uuid-aqui")
    .setApiUrl("https://api.biotrust.io")
    .setValidationMode(.faceMatch(requireChallenges: false))
    .build()

let launcher = BiometricValidationLauncher(
    viewController: self,
    callback: self,
    config: config
)

launcher.launch(from: self)

Conferir contra um documento (1:1)

FaceMatch Exact — conferência 1:1
let config = try FaceBiometricConfig.Builder()
    .setUuid("seu-uuid-aqui")
    .setApiUrl("https://api.biotrust.io")
    .setValidationMode(.faceMatchExact(documentNumber: "12345678901", requireChallenges: false))
    .build()

BiometricValidationLauncher(viewController: self, callback: self, config: config)
    .launch(from: self)

O resultado chega no seu callback em onFaceMatchComplete(result:), com match, uniqueID, fullName, document e similarity disponíveis no ValidationResult.

:::note Cadastro de pessoas O cadastro na base (com captura + prova de vida) é feito pela API de gestão do FaceMatch. Fale com o time BioTrust para habilitar o fluxo de cadastro no seu app. :::

Resultados da Validação

ValidationResult

O ValidationResult contém as informações da validação:

ValidationResult.swift
public class ValidationResult {
    public func getIsSuccess() -> Bool               // Se a validação foi bem-sucedida
    public func getMessage() -> String               // Mensagem de retorno
    public func getFaceImage() -> UIImage?           // Imagem do rosto capturada
    public func getDocumentResult() -> DocumentValidationResult? // Resultado do documento
    public func hasDocumentValidation() -> Bool       // Se inclui validação de documento
    public func getLivenessConfidence() -> Float      // Confiança de vivacidade (0.0-1.0)
}

DocumentValidationResult

O DocumentValidationResult contém as informações do documento:

DocumentValidationResult.swift
public class DocumentValidationResult {
    public func getSimilarityPercentage() -> Float   // Percentual de similaridade
    public func getFullName() -> String?            // Nome completo
    public func getCpf() -> String?                 // CPF
    public func getBirthDate() -> String?           // Data de nascimento
    public func getProbability() -> String?          // Probabilidade
    public func getIsAvailable() -> Bool             // Se o documento está disponível
}

SwiftUI

Para usar com SwiftUI, você precisa obter o UIViewController ativo:

SwiftUI Example
import SwiftUI
import BiometricFaceValidator

struct ContentView: View {
    @State private var launcher: BiometricValidationLauncher?
    
    var body: some View {
        VStack {
            Button("Iniciar Validação") {
                startValidation()
            }
        }
        .onAppear {
            BiometricFaceValidatorFramework.initializeFramework()
        }
    }
    
    private func startValidation() {
        guard let viewController = getRootViewController() else { return }
        
        let config = FaceBiometricConfig.Builder()
            .setUuid("seu-uuid-aqui")
            .setApiUrl("https://api.biotrust.io")
            .setValidationMode(.livenessOnly)
        
        do {
            let builtConfig = try config.build()
            let callback = MyValidationCallback()
            
            launcher = BiometricValidationLauncher(
                viewController: viewController,
                callback: callback,
                config: builtConfig
            )
            
            launcher?.launch(from: viewController)
        } catch {
            print("Erro: \(error)")
        }
    }
    
    private func getRootViewController() -> UIViewController? {
        guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
              let window = scene.windows.first(where: { $0.isKeyWindow }),
              let root = window.rootViewController else {
            return nil
        }
        
        var top = root
        while let presented = top.presentedViewController {
            top = presented
        }
        return top
    }
}

Personalização

Tema e Idioma

Theme and Locale
let config = FaceBiometricConfig.Builder()
    .setLocale("pt-BR")            // "en", "pt-BR", "es-ES"
    .setThemeMode("dark")           // "light", "dark", "system"

Imagem Personalizada

Custom Image
let customLogo = UIImage(named: "meu_logo")

let config = FaceBiometricConfig.Builder()
    .setCornerImage(customLogo)
    .setCornerImagePosition(.topRight)

Configurações Avançadas

Advanced Configuration
let config = FaceBiometricConfig.Builder()
    .setChallengeCount(5)                         // Número de desafios (1-5)
    .setRequireAllChallenges(false)              // Se todos os desafios são obrigatórios
    .setTimeout(60000)                            // Timeout em milissegundos (60s)
    .setEnableSoundFeedback(false)               // Desabilitar som
    .setEnableHapticFeedback(false)              // Desabilitar vibração

Utilidários do Launcher

O BiometricValidationLauncher possui métodos para configuração dinâmica:

Launcher Utilities
// Configurar locale
launcher.setLocale("en")

// Configurar tema
launcher.setThemeMode("light")

// Configurar modo de validação
launcher.setValidationMode(.livenessWithDocument)

// Configurar informações do documento
let documentInfo = DocumentInfo(cpf: "12345678901", birthDate: Date())
launcher.setDocumentInfo(documentInfo)

// Obter valores atuais
let currentLocale = launcher.getLocale()
let currentTheme = launcher.getThemeMode()
let currentMode = launcher.getValidationMode()

Tratamento de Erros

:::danger Erros Comuns Verifique sempre se as configurações estão corretas antes de iniciar a validação :::

Erros de Configuração

Error Handling
do {
    let config = try FaceBiometricConfig.Builder()
        .setUuid("uuid")
        .setApiUrl("api-url")
        .setValidationMode(.livenessWithDocument)
        // Erro: DocumentInfo é obrigatório para .livenessWithDocument
        .build()
} catch {
    print("Erro de configuração: \(error.localizedDescription)")
}

Validação de Documento

Document Validation
let documentInfo = DocumentInfo(cpf: "12345678901", birthDate: Date())

if documentInfo.isValid() {
    print("Documento válido")
} else {
    print("Documento inválido:")
    // Verificar CPF vazio, data inválida, etc.
}

Permissões de Câmera

Camera Permissions
import AVFoundation

func checkCameraPermission(completion: @escaping (Bool) -> Void) {
    switch AVCaptureDevice.authorizationStatus(for: .video) {
    case .authorized:
        completion(true)
    case .notDetermined:
        AVCaptureDevice.requestAccess(for: .video) { granted in
            DispatchQueue.main.async {
                completion(granted)
            }
        }
    default:
        completion(false)
    }
}

Best Practices

Gerenciamento de Memória

:::tip Memória Limpe sempre as referências para evitar vazamentos de memória :::

Memory Management
class ViewController: UIViewController {
    private var launcher: BiometricValidationLauncher?
    private var callback: MyValidationCallback?
    
    deinit {
        // Limpar referências
        launcher = nil
        callback = nil
    }
}

Validação de Entrada

Input Validation
func validateInput(uuid: String, apiUrl: String) -> Bool {
    // Validar UUID
    guard !uuid.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
        print("UUID não pode estar vazio")
        return false
    }
    
    // Validar URL
    guard URL(string: apiUrl) != nil else {
        print("URL da API inválida")
        return false
    }
    
    return true
}

Testes

:::danger Importante O SDK NÃO funciona no Simulador iOS. É necessário usar um dispositivo físico com câmera funcional. :::

Teste em Dispositivo Físico

Device Testing
func testIntegration() {
    // Verificar se o framework foi inicializado
    BiometricFaceValidatorFramework.initializeFramework()
    
    // Testar criação de configuração
    do {
        let config = try FaceBiometricConfig.Builder()
            .setUuid("test-uuid")
            .setApiUrl("https://api.test.com")
            .setValidationMode(.livenessOnly)
            .build()
        
        print("Configuração criada com sucesso")
    } catch {
        print("Erro na configuração: \(error)")
    }
}

Checklist de Implementação

Próximos Passos

Guia Android — o mesmo fluxo no Android
Guia Web — integração no navegador
App de exemplo (GitHub) — projeto completo funcionando
Playground — teste a validação ao vivo

Instalação​

Swift Package Manager​

Permissões​

Configuração Básica​

Inicialização do Framework​

Criando a Configuração​

Parâmetros de Configuração​

Parâmetros Obrigatórios​

Parâmetros Opcionais​

Modos de Validação​

Posições da Imagem​

Informações do Documento​

Implementação​

Criando o Launcher​

Implementando os Callbacks​

Iniciando a Validação​

Validação de Vivacidade Apenas​

Validação com Documento​

FaceMatch (Reconhecimento 1:N)​

Buscar na base (1:N)​

Conferir contra um documento (1:1)​

Resultados da Validação​

ValidationResult​

DocumentValidationResult​

SwiftUI​

Personalização​

Tema e Idioma​

Imagem Personalizada​

Configurações Avançadas​

Utilidários do Launcher​

Tratamento de Erros​

Erros de Configuração​

Validação de Documento​

Permissões de Câmera​

Best Practices​

Gerenciamento de Memória​

Validação de Entrada​

Testes​

Teste em Dispositivo Físico​

Checklist de Implementação​

Próximos Passos​