1. Introdução

A BCC Face é um biblioteca feita para ser integrada em uma aplicação iOS por um arquivo .framework. A biblioteca faz uso da câmera do dispositivo para fotografar a face para propósitos biométricos. Adicionalmente, a bibliteca provê um teste simples de vivacidade que requer que a pessoa sorria por alguns segundos e/ou olhe para algum lado especificado. O teste de vivacidade também possui a opção de falar as instruções facilitando o fluxo para os usuários.

Esse manual está atualizado para a versão 4.3.0 da BCCFace iOS.

1.1. Requisitos

2. Instalação

2.1. Instalando Dependências

1 - Adicione o seguinte Pod nas dependências da aplicação no Podfile:

pod 'GoogleMLKit/FaceDetection'

Note

Se a aplicação não possuir um Podfile, crie um na pasta raiz do seu projeto Xcode usando o comando pod init no terminal.

É preferível o uso de frameworks dinâmicos, Isso pode ser indicado usando a flag use_frameworks! no Podfile.

Um exemplo de Podfile com o alvo chamado BCCs-Sample é mostrado abaixo:

platform :ios, '13.0'
target 'BCCs-Sample' do
    # Comment the next line if you don't want to use dynamic frameworks
    use_frameworks!

    # Pods for BCCs-Sample
    pod 'GoogleMLKit/FaceDetection'

end

Important

É recomendado usar a versão mínima suportada do iOS para sua aplicação na qual é usada no framework: iOS 13.0, como no exemplo acima.

2 - Feche o projeto Xcode, abra o terminal, vá até a pasta onde o Podfile esta e execute:

$ pod install

Depois do término da execução, um arquivo com a extensão .xcworkspace será criado na mesma pasta.

3 - Abra o novo arquivo .xcworkspace.

Warning

A partir de agora, cada vez que o usuário quiser abrir o projeto, é necessário abrir através do arquivo .xcworkspace, pois ele inclui as dependências.

2.2. Importando e Configurando

2.2.1. Importando o Projeto

  • Abra o projeto usando o arquivo .xcworkspace.

  • Adicione o arquivo BCCFace.framework para o projeto, então adicione-o à lista de frameworks de sua aplicação.

    • Mova o arquivo .framework para a árvore de arquivos do projeto.

      Se já houver uma pasta de frameworks, é recomendado movê-lo para essa pasta.

    • Abra as configurações do projeto.

    • Vá para a guia General.

    • Clique e arraste o arquivo .framework para a árvore do projeto abaixo da sessão “Frameworks, Libraries, etc.”

  • Mude a configurção de BCCFace.framework de “Do not embed” para “Embed & Sign”.

  • Mude a versão alvo do seu projeto para o mínimo de iOS 13.

Note

É recomendado desabilitar o iPad como um alvo.

2.2.2. Configuração Inicial

Esta versão não possui dependências do Firebase e nem de uma configuração inicial chamada pelo AppDelegate. A única configuração inicial necessária é que o aplicativo deve solicitar permissão de uso da câmera. Para fazer isso, adicione a seguinte chave no arquivo info.plist, na Lista de Propriedades de Informação:

Privacy - Camera Usage Description

O valor da chave é a mensagem que será exibida ao usuário quando solicitar permissão de uso da câmera. Esse valor pode estar em branco ou ser uma mensagem customizada.

3. Uso

3.1. Parâmetros e Construtor

Para usar a biblioteca BCC Face corretamente, certos parâmetros são necessários. Um exemplo simples de uso de biblioteca é mostrado abaixo:

BCCFaceBuilder(self, delegate: self).initializeCapture()

O construtor da classe BCCFaceBuilder recebe os seguintes parâmetros:

  • hostVC: UIViewController - View controller que chama a tela de captura.

  • delegate: BCCFaceDelegate - Interface responsável por notificar os eventos de captura, como falha ou sucesso.

O método initialize também aceita um parâmetro opcional, como monstrado abaixo:

public func initializeCapture(
    _ navController: UINavigationController? = nil
) { ... }

Nos casos de a navegação ser feita através de um navigation controller, você deve fornecê-lo ao chamar o método.

A classe BCCFaceBuilder é responsável por gerenciar as configurações de uso do BCCFace. Os parâmetros a seguir são aceitos para confiuração da captura biométrica e comportamento do software.

  • buildSmileCheck(with smileProbability: ClosedRange\<Float> = 0.5...1.0) - Adiciona verificação de sorriso para detecção de vivacidade e define o valor de aceitação.

  • removeSmileCheck() - Remove a verificação de sorriso.

  • buildRotationCheck(_ rotationChecks: [HeadRotationCheck], headRotationAngle: ClosedRange\<Float> = -6.0...6.0) - Define uma lista de testes de vivacidade para rotação de face e o ângulo máximo de rotação. As opções são:

    enum class HeadRotationCheck {
        case randomRotation
        case leftRotation
        case rightRotation
    }
    
  • removeHeadRotation() - Remove o teste de rotação de face.

  • buildSpeechSettings(_ speechSettings: SpeechSettings) - Define os critérios para a configuração de acessibilidade (leitura das instruções) usando os seguintes parâmetros:

    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 iniciarão silenciadas ou não (true para silenciar).

    • pitch - Define o timbre de voz para as instruções entre 0.5 (grave) e 2.0 (agudo).

    • speed - Define a velocidade de leitura das instruções.

    Os valores predeterminados podem ser acessados através da seguinte variável estática:

    public static let defaultSpeechSettings = SpeechSettings(
        volume: 1.0,
        startsMuted: true,
        pitch: 1.0,
        speed: 0.5
    )
    
  • removeSpeech() - Remove a leitura de acessibilidade.

  • setReviewEnable(_ enable: Booln) - Define se a tela de revisão da captura biométrica será habilitada ou não.

  • setInstructionEnable(_ enable: Bool) - Define se a tela de instruções será habilitada ou não.

  • forceLanguage(_ language: BCCLanguages?) - Força as instruções a serem exibidas em um idioma específico. Se o idioma do dispositivo não for suportado, inglês será usado. Os idiomas suportados são:

    public enum BCCLanguages: String {
        case ptBR = "pt-BR"
        case enUS = "en"
        case esMX = "es"
        case deviceLanguage = "deviceLanguage"
    }
    
  • removeLanguage() - Remove o idioma forçado.

Para referência, a lista completa de parâmetros e valores padrão é:

var headRotationAngle: ClosedRange<Float> = -6.0...6.0
var openEyesProbability: ClosedRange<Float> = 0.8...1.1
var smileProbability: ClosedRange<Float> = 0.5...1.0
var livenessChecks: [LivenessChecks] = [.smileDetection, .headRotationRandom]
var speechSettings: SpeechSettings? = .defaultSpeechSettings
var language: BCCLanguages? = nil
var showPhotoReview: Bool = false

3.2. Valores de Retorno

Os resultados da última captura facial podem ser recuperados através do método faceCaptureDidFinish da interface BCCFaceDelegate:

func faceCaptureDidFinish(
  data: BCCFaceReturnData,
  analytics: BCCFaceReturnAnalytics
)

O objeto data contém ambas as imagens capturadas durante o processo.

public struct BCCFaceReturnData {
  public internal(set) var photo: UIImage
  public internal(set) var croppedPhoto: UIImage?
}

Caso o usuário encerre a aplicação antes de finalizar a captura bionmétrica, o método faceCaptureDidAbort será chamado. Você pode implementar este método para tratar este cenário.

3.3. Projeto Exemplo

Este é um exemplo de projeto funcional para captura de face utilizando o BCC Mobile Face iOS:

import UIKit
import BCCFace

class ViewController: UIViewController {

    @IBOutlet weak var photoTaken: UIImageView!
    @IBOutlet weak var startCaptureButton: UIButton!

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func startCapture(_ sender: UIButton) {
        BCCFaceBuilder(self, delegate: self)
            .initializeCapture(navigationController)
    }
}

extension ViewController: BCCFaceDelegate {

    func faceCaptureDidFinish(
        data: BCCFace.BCCFaceReturnData,
        analytics: BCCFace.BCCFaceAnalytics
    ) {
        self.photoTaken.contentMode = .scaleAspectFill
        self.photoTaken.image = data.photo
    }

    func faceCaptureDidAbort(
        analytics: BCCFace.BCCFaceAnalytics
    ) {
        // ...
    }

}