> For the complete documentation index, see [llms.txt](https://docs.griaule.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.griaule.com/sdks/bcc-face/bccmobilefaceios.md). # iOS **BCC Face** é uma biblioteca destinada a ser integrada numa aplicação iOS a partir de um `.framework` ficheiro. Utiliza a câmara do dispositivo para tirar uma fotografia de um rosto para fins biométricos. Fornece um teste simples de vivacidade ativa, exigindo que a pessoa sorria durante cerca de um segundo e/ou olhe para a direita ou para a esquerda. O teste de vivacidade inclui uma opção para falar as instruções, tornando o fluxo de trabalho mais fácil para os utilizadores. Além disso, fornece um teste de vivacidade passiva que pode ser utilizado para verificar se a fotografia foi tirada a uma pessoa real sem exigir interação do utilizador. Este manual está atualizado para a versão iOS do BCC Face Mobile `4.12.2`. {% hint style="warning" %} O **teste de vivacidade passiva** está disponível apenas a partir da versão `4.4.0` em diante. {% endhint %} ### Requisitos * Git * CocoaPods, disponível em . ### Instalação #### Instalando Dependências 1 - Adicione os seguintes Pods às dependências da aplicação no Podfile: ```ruby pod 'lottie-ios' ``` {% hint style="info" %} Se a aplicação não tiver um Podfile, ele pode ser criado na pasta raiz do seu projeto Xcode usando o `pod init` comando no terminal. O Podfile não aparecerá diretamente no Xcode; será criado no diretório do projeto. {% endhint %} É preferível usar frameworks dinâmicos. Isto pode ser indicado usando a flag `use_frameworks!` no Podfile. Um exemplo de Podfile com um target chamado **BCCs-Sample** é mostrado abaixo: ```ruby platform :ios, '15.5' target 'BCCs-Sample' do use_frameworks! pod 'lottie-ios' fim post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['DEVELOPMENT_TEAM'] = "YOUR_DEVELOPMENT_TEAM_KEY" config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' fim fim fim ``` {% hint style="warning" %} Nas versões anteriores da BCC Face Lib iOS, também era necessário declarar `pod 'GoogleMLKit/FaceDetection'` no Podfile da aplicação. A partir da **versão 4.12.2**, se a aplicação tiver esta dependência, **é recomendado removê-la** e executar `pod install` novamente. A BCC Face Lib já inclui o MLKit internamente; manter esta declaração do pod causará avisos de classes duplicadas que podem levar a instabilidade no arranque da aplicação. {% endhint %} {% hint style="warning" %} Recomenda-se usar na sua aplicação a mesma versão mínima do iOS suportada por este framework: iOS 15.5, como no exemplo acima. Também é aconselhável definir a flag `BUILD_LIBRARY_FOR_DISTRIBUTION = YES` no Podfile para garantir compatibilidade com versões mais antigas do SDK. {% endhint %} 2 - Feche o projeto Xcode, abra um terminal, vá para a pasta onde o Podfile está localizado e, em seguida, execute: ```bash pod install ``` Após a execução terminar, será criado na mesma pasta um ficheiro com a extensão `.xcworkspace` . 3 - Abra o novo `.xcworkspace` ficheiro. {% hint style="warning" %} A partir de agora, sempre que o utilizador quiser abrir o projeto, ele deve ser aberto através deste `.xcworkspace` ficheiro, pois inclui as dependências. {% endhint %} #### Importação e Configuração **Importando o Projeto** * Abra o projeto usando o `.xcworkspace` ficheiro. * Adicione o `BCCFace.framework` ficheiro ao projeto e, em seguida, adicione-o à lista de frameworks da sua aplicação. * Mova o `.framework` ficheiro para a árvore de ficheiros do projeto. * Se já existir uma pasta frameworks, é recomendado mover o ficheiro para lá. * Abra as definições do projeto. * Vá para o *separador Geral*. * Clique e arraste o `.framework` da árvore do projeto para a secção `Frameworks, Libraries and Embedded Content` . * Altere a definição `BCCFace.framework` de `Não incorporar` para `Incorporar e Assinar`. * Altere a versão de destino do seu projeto para um mínimo de iOS 15.5. {% hint style="info" %} É recomendado desativar o iPad como target. {% endhint %} **Configuração Inicial** Esta versão não tem dependências do Firebase, nem requer uma configuração inicial chamada a partir do AppDelegate. A única configuração inicial necessária é que a aplicação deve solicitar permissão para usar a câmara. Para isso, adicione a seguinte chave ao `info.plist` ficheiro, na Lista de Propriedades de Informação: ```properties Chave : Privacy - Camera Usage Description Valor : Permitir acesso à câmara ``` O valor da chave é uma mensagem mostrada ao utilizador quando é solicitada a permissão de uso da câmara. Este valor pode ser deixado em branco ou preenchido com uma mensagem personalizada. ### Utilização #### Parâmetros e Construtor Para usar corretamente a biblioteca BCC Face, existem alguns parâmetros obrigatórios. Um exemplo simples de utilização da biblioteca é mostrado abaixo: ```swift BCCFaceBuilder(self, delegate: self).initializeCapture() ``` *** O `BCCFaceBuilder` construtor da classe recebe os seguintes parâmetros: * `hostVC: UIViewController` - Controlador de visualização que chama o ecrã de captura. * `delegate: BCCFaceDelegate` - Interface responsável por notificar eventos de captura (por exemplo, falha ou sucesso). *** O `initializeCapture` método também aceita um parâmetro opcional, como mostrado abaixo: ```swift public func initializeCapture( _ navController: UINavigationController? = nil ) { // ... } ``` Se quiser que a navegação aconteça através de um navigation controller, deve fornecê-lo ao chamar o método. *** `BCCFaceBuilder` é a classe responsável por tratar a configuração de utilização de `BCCFace`. Os seguintes parâmetros são aceites para configurar a captura biométrica e o comportamento do software: * `buildSmileCheck(with smileProbability: ClosedRange = 0.5...1.0)` - Adiciona o sorriso ao teste de vivacidade e define o limiar de aceitação. Esta funcionalidade está ativada por predefinição. * `removeSmileCheck()` - Remove o sorriso do teste de vivacidade. * `buildRotationCheck(_ rotationChecks: [HeadRotationCheck], headRotationAngle: ClosedRange = -6.0...6.0)` - Define uma lista de testes de vivacidade por rotação da cabeça e o ângulo máximo de rotação. Esta funcionalidade está ativada por predefinição. As opções de rotação da cabeça são: ```swift enum class HeadRotationCheck { case randomRotation case leftRotation case rightRotation } ``` * `removeHeadRotation()` - Remove a rotação da cabeça do teste de vivacidade. * `addPassiveLiveness()` - Adiciona o teste de vivacidade passiva. Esta funcionalidade é usada para verificar se a fotografia capturada é de uma pessoa real sem exigir qualquer interação do utilizador. Para usar esta funcionalidade, DEVE desativar as verificações de vivacidade ativa (`removeSmileCheck()` e `removeHeadRotation()`), que são adicionadas por predefinição. * `buildSpeechSettings(_ speechSettings: SpeechSettings)` - Define os critérios para a fala de acessibilidade, utilizando os seguintes parâmetros: ```swift class SpeechSettings( public let volume: Float public let startsMuted: Bool public let pitch: Float public let speed: Float ) ``` * `volume` - O volume de áudio entre `0.0` e `1.0`. * `startsMuted` - Define se as instruções começam silenciadas ou não (`true` para silenciado). * `pitch` - Define o tom de voz das instruções entre `0.5` (baixo) e `2.0` (alto). * `speed` - Define a velocidade da voz das instruções. Este valor deve ser positivo. Os valores predefinidos podem ser acedidos através da variável estática: ```swift public static let defaultSpeechSettings = SpeechSettings( volume: 1.0, startsMuted: true, pitch: 1.0, speed: 0.5 ) ``` * `removeSpeech()` - Remove a fala de acessibilidade. * `setInstructionEnable(_ enable: Bool)` - Define se o ecrã de instruções está ativado ou desativado. * `forceLanguage(_ language: BCCLanguages?)` - Força as instruções a serem apresentadas numa única língua. Se a língua do dispositivo não for suportada, será usado inglês. As línguas suportadas são: ```swift public enum BCCLanguages: String { case ptBR = "pt-BR" case enUS = "en" case esMX = "es" case deviceLanguage = "deviceLanguage" } ``` * `enableFlashButton(_ enable: Bool)` - Ativa (`true`) ou desativa (`false`) o botão do flash na câmara traseira. Predefinição: desativado (`false`). * `enableManualCapture(_ enable: Bool)` - Ativa (`true`) ou desativa (`false`) o botão de captura manual, que permite contornar as verificações de captura automática. Ao realizar uma captura manual, o utilizador poderá rever a fotografia capturada antes de terminar o processo. * `setImageCompressionFormat(_ format: ImageCompressionFormat)` - Define o formato de compressão de uma captura de vivacidade passiva. Pode escolher entre `.jpeg` (predefinição) ou `.jpeg2000`. * `enableIntegrityValidation(clientSecret: Data, nonce: Data)` - Ativa a validação de integridade para vivacidade passiva, uma camada extra de segurança para garantir a integridade do payload. Como referência, aqui está uma lista completa de parâmetros e valores predefinidos: ```swift var headRotationAngle: ClosedRange = -6.0...6.0 var openEyesProbability: ClosedRange = 0.8...1.1 // Obsoleto desde 4.12.2 var smileProbability: ClosedRange = 0.5...1.0 var livenessChecks: [LivenessChecks] = [.smileDetection] var headRotationChecks: [HeadRotationCheck] = [.randomRotation] var speechSettings: SpeechSettings? = .defaultSpeechSettings var cameraSettings: CameraSettings = .defaultCameraSettings var canEnableManualCapture: Bool = false var canEnableFlash: Bool = true var language: BCCLanguages? = nil var showInstructions: Bool = false var imageCompressionFormat: ImageCompressionFormat = .jpeg var integrityValidationData: IntegrityValidationData? = nil ``` {% hint style="warning" %} O teste de vivacidade ativa (usando sorriso e rotação aleatória da cabeça) está ativado por predefinição. Para usar apenas a verificação de vivacidade passiva, antes de a adicionar, deve remover os métodos de vivacidade ativa do builder: ```swift BCCFaceBuilder(self, delegate: self) .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() ``` {% endhint %} Aqui está um snippet de código para inicializar uma captura usando apenas o teste de vivacidade passiva: ```swift // A partir do ViewController pretendido... // Criar o builder let faceBuilder = BCCFaceBuilder(self, delegate: self) // Configurar o builder faceBuilder .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() // Inicializar a captura a partir do builder faceBuilder.initializeCapture(self.navigationController) ``` #### Valores de Retorno Os resultados da última captura facial podem ser obtidos usando o `faceCaptureDidFinish` método da `interface BCCFaceDelegate` : ```swift func faceCaptureDidFinish( data: BCCFaceReturnData, analytics: BCCFaceReturnAnalytics ) ``` O `data` o objeto contém as imagens capturadas durante o processo: ```swift public struct BCCFaceReturnData { // Anteriormente 'photo', renomeado para seguir o mesmo padrão que no Android public internal(set) var originalPhoto: UIImage public internal(set) var croppedPhoto: UIImage? // Resultado da vivacidade passiva public internal(set) var passiveResult: Data? // API LEGADA: igual a 'originalPhoto' public var photo: UIImage { self.originalPhoto } } ``` As propriedades devolvidas são: * `originalPhoto` (*imagem*) - A fotografia original tirada pela câmara. * `croppedPhoto` (*imagem*) - A fotografia recortada, que é a imagem do rosto recortada da fotografia original. * `passiveResult` (*Data*) - Conteúdo do ficheiro da recolha de vivacidade passiva. Só está presente se a captura for bem-sucedida. É o retorno da recolha de vivacidade passiva como *Dados JPEG* ou *JPEG 2000*. Estes dados podem ser guardados/exportados diretamente para um ficheiro ou enviados pela rede (para transmissão em rede, os dados podem ser facilmente codificados, por exemplo, como uma string Base64). Se o utilizador abortar a captura ou se ocorrer qualquer falha durante o processo, o `faceCaptureDidAbort` método será chamado. Pode implementar este método para tratar este cenário. #### Projeto de Exemplo Este é um projeto de exemplo funcional para captura facial usando BCC Mobile Face iOS: ```swift import UIKit import BCCFace class ViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() } @IBAction func startCapture(_ sender: UIButton) { BCCFaceBuilder(self, delegate: self) .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() .buildCameraSettings(.frontSwitchable) .enableFlashButton(true) .initializeCapture(navigationController) } } extension ViewController: BCCFaceDelegate { func faceCaptureDidFinish( data: BCCFace.BCCFaceReturnData, analytics: BCCFace.BCCFaceAnalytics ) { // ... } func faceCaptureDidAbort( analytics: BCCFace.BCCFaceAnalytics ) { // ... } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceios.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.