# iOS **BCC Face** é uma biblioteca destinada a ser integrada em uma aplicação iOS a partir de um `.framework` arquivo. Ela usa a câmera do dispositivo para tirar uma foto de um rosto para fins biométricos. Ela fornece um teste simples de liveness ativo, exigindo que a pessoa sorria por cerca de um segundo e/ou olhe para a direita ou para a esquerda. O teste de liveness inclui uma opção para falar as instruções, facilitando o fluxo de trabalho para os usuários. Além disso, ela fornece um teste de liveness passivo que pode ser usado para verificar se a foto foi tirada de uma pessoa real sem exigir interação do usuário. Este manual está atualizado para a versão BCC Face Mobile iOS `4.11.3`. {% hint style="warning" %} O **teste de liveness passivo** 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 'GoogleMLKit/FaceDetection' ``` {% hint style="info" %} Se a aplicação não possuir um Podfile, ele pode ser criado na pasta raiz do seu projeto Xcode usando o comando `pod init` no terminal. O Podfile não aparecerá diretamente no Xcode; ele será criado no diretório do projeto. {% endhint %} É preferível usar frameworks dinâmicos. Isso 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.0' target 'BCCs-Sample' do use_frameworks! pod 'GoogleMLKit/FaceDetection' pod 'lottie-ios' end 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' end end end ``` {% hint style="warning" %} Recomenda-se usar a mesma versão mínima do iOS suportada pela sua aplicação que a deste framework: iOS 15.0, como no exemplo acima. Também é aconselhável definir a `BUILD_LIBRARY_FOR_DISTRIBUTION = YES` flag no Podfile para garantir compatibilidade com versões mais antigas do SDK. {% endhint %} 2 - Feche o projeto Xcode, abra um terminal e vá até a pasta onde está o Podfile, e então execute: ```bash pod install ``` Após a execução terminar, um arquivo com a extensão `.xcworkspace` será criado na mesma pasta. 3 - Abra o novo `.xcworkspace` arquivo. {% hint style="warning" %} A partir de agora, sempre que o usuário quiser abrir o projeto, é necessário abri-lo por meio deste `.xcworkspace` arquivo, pois ele inclui as dependências. {% endhint %} ### Importação e Configuração #### Importando o Projeto * Abra o projeto usando o `.xcworkspace` arquivo. * Adicione o `BCCFace.framework` arquivo ao projeto, depois adicione-o à lista de frameworks da sua aplicação. * Mova o `.framework` arquivo para a árvore de arquivos do projeto. * Se já houver uma pasta de frameworks, é recomendável mover o arquivo para lá. * Abra as configurações do projeto. * Vá para a aba *General* . * Clique e arraste o `.framework` para a árvore do projeto na seção `Frameworks, Libraries, etc.` * Altere a configuração `BCCFace.framework` de `Do not embed` para `Embed & Sign`. * Altere a versão de destino do seu projeto para um mínimo de iOS 15. {% hint style="info" %} Recomenda-se desativar iPad como destino. {% endhint %} #### Configuração Inicial Esta versão não possui dependências do Firebase, nem de uma configuração inicial chamada pelo AppDelegate. A única configuração inicial necessária é que a aplicação deve solicitar permissão de uso da câmera. Para isso, adicione a seguinte chave no arquivo `info.plist` , na Information Property List: ```properties Chave : Privacy - Camera Usage Description Valor : Allow access to camera ``` O valor da chave é uma mensagem que será mostrada ao usuário ao solicitar permissão de uso da câmera. Esse valor pode estar em branco ou preenchido com uma mensagem personalizada. ## Uso ### Parâmetros e Construtor Para usar corretamente a biblioteca BCC Face, há alguns parâmetros obrigatórios. Abaixo é mostrado um exemplo simples de uso da biblioteca: ```swift BCCFaceBuilder(self, delegate: self).initializeCapture() ``` *** O `BCCFaceBuilder` o construtor da classe recebe os seguintes parâmetros: * `hostVC: UIViewController` - Controlador de visualização que chama a tela de captura. * `delegate: BCCFaceDelegate` - Interface responsável por notificar eventos de captura (por exemplo, falha ou sucesso). *** O `initializeCapture` o método também aceita um parâmetro opcional, conforme mostrado abaixo: ```swift public func initializeCapture( _ navController: UINavigationController? = nil ) { // ... } ``` Se você quiser que a navegação ocorra por meio de um navigation controller, deve fornecê-lo ao chamar o método. *** O `BCCFaceBuilder` a classe é responsável por lidar com a configuração de uso para `BCCFace`. Os seguintes parâmetros são aceitos para configurar a captura biométrica e o comportamento do software: * `buildSmileCheck(with smileProbability: ClosedRange = 0.5...1.0)` - Adiciona sorriso para o teste de liveness e define o limite de aceitação. Este recurso está habilitado por padrão. * `removeSmileCheck()` - Remove o sorriso da verificação de liveness. * `buildRotationCheck(_ rotationChecks: [HeadRotationCheck], headRotationAngle: ClosedRange = -6.0...6.0)` - Define uma lista de testes de liveness para rotação da cabeça e o ângulo máximo de rotação. Este recurso está habilitado por padrã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 da verificação de liveness. * `addPassiveLiveness()` - Adiciona o teste de liveness passivo. Este recurso é usado para verificar se a foto capturada é de uma pessoa real sem exigir qualquer interação do usuário. Para usar este recurso, você DEVE desativar as verificações de liveness ativas (`removeSmileCheck()` e `removeHeadRotation()`) que são adicionadas por padrão. * `buildSpeechSettings(_ speechSettings: SpeechSettings)` - Define os critérios para fala de acessibilidade, usando 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 do áudio entre `0.0` e `1.0`. * `startsMuted` - Define se as instruções começam no mudo ou não (`true` para mudo). * `pitch` - Define o tom da voz das instruções entre `0.5` (baixo) e `2.0` (alto). * `speed` - Define a velocidade da voz das instruções. Esse valor deve ser positivo. Os valores pré-definidos podem ser acessados por meio 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 a tela de instruções está ativada ou desativada. * `forceLanguage(_ language: BCCLanguages?)` - Força que as instruções sejam exibidas em um único idioma. Se o idioma do dispositivo não for suportado, o inglês será usado. Os idiomas suportados 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 de flash na câmera traseira. Padrão: desativado (`false`). * `enableManualCapture(_ enable: Bool)` – Ativa (`true`) ou desativa (`false`) o botão de captura manual, permitindo que o usuário ignore as verificações automáticas de captura. Ao realizar uma captura manual, o usuário poderá revisar a foto capturada antes de concluir o processo. * `setImageCompressionFormat(_ format: ImageCompressionFormat)` – Define o formato de compressão para uma captura de liveness passivo. As opções disponíveis são `.jpeg` (padrão) ou `.jpeg2000`. * `enableIntegrityValidation(clientSecret: Data, nonce: Data)` – Ativa a validação de integridade para a detecção de liveness passivo, adicionando uma camada extra de segurança para garantir a integridade do payload. Para referência, aqui está uma lista completa de parâmetros e valores padrão: ```swift var headRotationAngle: ClosedRange = -6.0...6.0 var openEyesProbability: ClosedRange = 0.8...1.1 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 liveness ativo (usando sorriso e rotação aleatória da cabeça) está habilitado por padrão. Para usar apenas a verificação de liveness passivo, antes de adicioná-la, é necessário remover os métodos de liveness ativo do construtor: ```swift BCCFaceBuilder(self, delegate: self) .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() ``` {% endhint %} Aqui está um trecho de código para inicializar uma captura usando apenas o teste de liveness passivo: ```swift // A partir do ViewController desejado... // 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 recuperados 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 estar em conformidade com o mesmo padrão do Android public internal(set) var originalPhoto: UIImage public internal(set) var croppedPhoto: UIImage? // Resultado de Liveness Passivo public internal(set) var passiveResult: Data? // API LEGADA: mesmo que 'originalPhoto' public var photo: UIImage { self.originalPhoto } } ``` As propriedades retornadas são: * `originalPhoto` (*imagem*) - A foto original tirada pela câmera. * `croppedPhoto` (*imagem*) - A foto recortada, que é a imagem do rosto recortada da foto original. * `passiveResult` (*Data*) - Conteúdo do arquivo da coleta para liveness passivo. Está presente apenas se tiver sido capturado com sucesso. É o retorno da coleta para liveness passivo como *Dados JPEG*. Esses dados podem ser salvos/exportados diretamente para um arquivo ou enviados para a rede (para rede: a codificação do sistema pode ser feita facilmente, por exemplo, string Base64). Se o usuário abortar a captura, fechando antes de capturar as biometria, o método `faceCaptureDidAbort` será chamado. Você pode implementar este método para tratar esse cenário. ### Projeto de Exemplo Este é um projeto de exemplo funcional para uma 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 ) { // ... } } ``` ## Instruções do Agente: Consultando Esta Documentação Se você precisar de informações adicionais que não estejam diretamente disponíveis nesta página, você pode consultar a documentação dinamicamente fazendo uma pergunta. Faça uma solicitação HTTP GET na URL da página atual com o parâmetro de consulta `ask` : ``` GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceios.md?ask= ``` A pergunta deve ser específica, autônoma e escrita em linguagem natural. A resposta conterá uma resposta direta à pergunta e trechos e fontes relevantes da documentação. Use este mecanismo quando a პასუხa não estiver explicitamente presente na página atual, você precisar de esclarecimentos ou contexto adicional, ou quiser recuperar seções relacionadas da documentação. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceios.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.