Guia de uso SDK BioTrust - iOS

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

Pré-requisitos

iOS 15.0 ou superior (somente dispositivos físicos)
Xcode 16 ou superior
Dispositivo físico (não funciona no Simulador)
Câmera frontal funcional

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.1.0")
],
targets: [
    .target(
        name: "SeuApp",
        dependencies: [
            .product(name: "BioTrust", package: "BioTrust-SDK-IOS-Release")
        ]
    )
]

No código, importe o módulo:

import BioTrust

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 BioTrust

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BioTrustFramework.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
    case faceCapture                                              // Prova de vida, sem consulta a bases
}

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 BioTrust

class ViewController: UIViewController {
    private var launcher: BiometricValidationLauncher?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        BioTrustFramework.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 o usuário fecha a tela antes de concluir
    func onValidationCancelled() {
        print("Validação cancelada")
    }
    
    // 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)

O FaceMatch identifica pessoas por comparação facial com as pessoas cadastradas na conta. O fluxo é composto pelo cadastro das pessoas e pela identificação (1:N) ou verificação (1:1).

Buscar na base (1:N)

Executa a prova de vida e busca o rosto entre as pessoas cadastradas, retornando a correspondência de maior similaridade.

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 é entregue em onFaceMatchComplete(result:), com os campos match, uniqueID, fullName, document e similarity do ValidationResult.

Cadastro de pessoas

O cadastro de pessoas é realizado pela API de gestão do FaceMatch. Entre em contato com a BioTrust para habilitar o fluxo de cadastro na sua aplicação.

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 (720 × 960)
    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
    public func getIsApproved() -> Bool              // Identidade confirmada
}

Validação com documento

No modo livenessWithDocument, o sucesso indica que a identidade foi confirmada: biometria disponível na base de documentos e similaridade igual ou superior ao limite mínimo da plataforma. O resultado do documento é retornado também quando a identidade não é confirmada.

SwiftUI

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

SwiftUI Example
import SwiftUI
import BioTrust

struct ContentView: View {
    @State private var launcher: BiometricValidationLauncher?
    
    var body: some View {
        VStack {
            Button("Iniciar Validação") {
                startValidation()
            }
        }
        .onAppear {
            BioTrustFramework.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

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

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

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
    BioTrustFramework.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
Guia .NET MAUI — integração em aplicativos .NET MAUI
Controle de acesso — modo terminal com BTAccessSession
Webhooks — notificação de eventos para o seu servidor
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​