1. Introdução

A BCC Face é um biblioteca feita para ser integrada em uma aplicação iOS por um arquivo .framework.

A biblioteca utiliza a câmera do dispositivo para tirar uma foto da face para propósitos biométricos. Ela provê um teste simples de vivacidade ativo, requerendo que a pessoa sorria por alguns segundos e/ou olhe para a direita ou esquerda. O teste de vivacidade inclui uma opção para falar as instruções, facilitando o fluxo para os usuários. Adicionalmente, ela provê um teste de vivacidade passivo que pode ser usado para verificar se a foto foi tirada de uma pessoa real sem requerer interação do usuário.

Esse manual está atualizado para a versão 4.4.0 do BCC Face Mobile iOS.

Attention

O teste de vivacidade passivo está disponível somente a partir da versão 4.4.0.

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
    use_frameworks!

    pod 'GoogleMLKit/FaceDetection', '~> 3.0.0'
    pod 'lottie-ios', '~> 3.3.0'
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

Important

É recomendado utilizar a mesma versão mínima de iOS suportada para a aplicação e para o framework: iOS 13.0, como no exemplo acima.

2 - Feche o projeto Xcode, abra o terminal, vá até a pasta onde o Podfile está 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 ao 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 seção “Frameworks, Libraries, etc.”

  • Mude a configuração do 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 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:

Key    :  Privacy - Camera Usage Description
Value  :  Permitir acesso à câmera

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 initializeCapture também aceita um parâmetro opcional, como mostrado abaixo:

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

Nos casos em que a navegação é 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 configuração da captura biométrica e comportamento do software:

  • buildSmileCheck(with smileProbability: ClosedRange\<Float> = 0.5...1.0) - Adiciona o teste de vivacidade por meio de verificação de sorriso e define o limiar de aceitação. Essa funcionalidade é ativada por padrão.

  • removeSmileCheck() - Remove o teste de vivacidade por meio 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. Essa funcionalidade é ativada por padrão. As opções para rotação de face são: 

    enum class HeadRotationCheck {
    case randomRotation
    case leftRotation
    case rightRotation
}

  • removeHeadRotation() - Remove o teste de vivacidade por meio de rotação de face.

  • addPassiveLiveness() - Adiciona o teste de vivacidade passivo. Essa funcionalidade é usada para verificar se a foto capturada é de uma pessoa real sem requerer interação do usuário. Para usar essa funcionalidade, você DEVE desabilitar os testes de vivacidade ativos (removeSmileCheck() e removeHeadRotation()) que são adicionados por padrão.

  • 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. Este valor deve ser positivo.

    Os valores predeterminados podem ser acessados por meio 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: Bool) - 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 smileProbability: ClosedRange<Float> = 0.5...1.0
var headRotationAngle: ClosedRange<Float> = -6.0...6.0
var openEyesProbability: ClosedRange<Float> = 0.8...1.1
var livenessChecks: [LivenessChecks] = [.smileDetection, .headRotationRandom]
var speechSettings: SpeechSettings? = .defaultSpeechSettings
var language: BCCLanguages? = nil
var showPhotoReview: Bool = false

Attention

O teste de vivacidade ativo (usando sorriso e rotação aleatória de cabeça) é habilitado por padrão. Para usar apenas o teste de vivacidade passivo, antes de adicioná-lo, é necessário remover os métodos de vivacidade ativa do construtor:

BCCFaceBuilder(self, delegate: self)
    .removeSmileCheck()
    .removeHeadRotation()
    .addPassiveLiveness()

Aqui está um trecho de código para iniciar uma captura usando apenas o teste de vivacidade passivo:

// Do ViewController desejado...

// Crie o builder
let faceBuilder = BCCFaceBuilder(self, delegate: self)

// Configure o builder
faceBuilder
    .removeSmileCheck()
    .removeHeadRotation()
    .addPassiveLiveness()

// Inicie a captura a partir do builder
faceBuilder.initializeCapture(self.navigationController)

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 as imagens capturadas durante o processo:

public struct BCCFaceReturnData {
    // Previamente 'photo', renomeado para seguir o mesmo padrão do Android
    public internal(set) var originalPhoto: UIImage
    public internal(set) var croppedPhoto: UIImage?

    // Resultado do teste de vivacidade passivo
    public internal(set) var passiveResult: Data?

    // API LEGADA: o mesmo que 'originalPhoto'
    public var photo: UIImage { self.originalPhoto }
}

As propriedades retornadas são:

  • originalPhoto (image) - Foto original tirada pela câmera.
  • croppedPhoto (image) - Foto cortada, que é a imagem da face recortada da foto original.
  • passiveResult (Data) - Conteúdo do arquivo de coleta para teste de vivacidade passivo. Está presente apenas se capturado com sucesso. É o retorno da coleta para teste de vivacidade passivo como JPEG Data. Esses dados podem ser salvos/exportados diretamente para um arquivo ou enviados para a rede (para rede: a codificação do sistema pode ser facilmente feita, por exemplo, uma string Base64).

Caso o usuário encerre a aplicação antes de finalizar a captura biomé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
    ) {
        // ...
    }
}