iOS

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.8.0 do BCC Face Mobile iOS.

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

Requisitos

Git
CocoaPods, disponível em https://cocoapods.org/.

Instalação

Instalando Dependências

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

pod 'GoogleMLKit/FaceDetection'

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. O Podfile não aparecerá diretamente no Xcode; ele será criado no diretório do projeto.

É 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, '15.0'

target 'BCCs-Sample' do
	use_frameworks!

	pod 'GoogleMLKit/FaceDetection', '~> 6.0.0'
	pod 'lottie-ios', '~> 4.5.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

Na versão atual do BCC Face Mobile iOS (4.8.0), é necessário utilizar a versão 4.5.0 da dependência lottie-ios, conforme especificado no exemplo acima, para garantir compatibilidade e evitar conflitos de versão.

É recomendado utilizar a mesma versão mínima de iOS suportada para a aplicação e para o framework: iOS 15.0, como no exemplo acima. Também é indicado definir a flag BUILD_LIBRARY_FOR_DISTRIBUTION = YES no Podfile, garantindo compatibilidade com versões mais antigas do SDK.

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.

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.

Importando e Configurando

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 15.

É recomendado desabilitar o iPad como alvo.

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.

Uso

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

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)

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.

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 {
	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
	) {
		// ...
	}
}

Exemplo de chamada para API de Liveness

Esse exemplo demonstra uma chamada para API de Liveness com o resultado de Captura Passiva, o que ajuda a mitigar possíveis ataques.

import Foundation

struct Credentials { let username: String; let password: String }

final class LivenessService {
    private let baseURL: URL
    private let session: URLSession
    private let encoder = JSONEncoder()
    private let decoder = JSONDecoder()
    
    init(baseURL: URL, session: URLSession = .shared) {
        self.baseURL = baseURL
        self.session = session
    }

    func getToken(using creds: Credentials) async throws -> String {
        let endpoint = URL(string: "gbds/v2/tokens", relativeTo: baseURL)!
        var request = URLRequest(url: endpoint)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        let body = TokenRequest(
            data: AuthData(
                grantType: "CREDENTIALS",
                userName: creds.username,
                userPassword: creds.password
            )
        )
        request.httpBody = try encoder.encode(body)

        let (data, _) = try await session.data(for: request)
        let decoded = try decoder.decode(TokenResponse.self, from: data)
        return decoded.data.token
    }

    func checkLiveness(passiveResultInBase64: String, bearer token: String) async throws -> LivenessResult {
        let endpoint = URL(string: "gbds/v2/liveness", relativeTo: baseURL)!
        var request = URLRequest(url: endpoint)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")

        let body = LivenessRequest(
            data: LivenessData(
                source: "ORIGINAL",
                type: "FACE",
                format: "JPEG",
                content: passiveResultInBase64
            )
        )
        request.httpBody = try encoder.encode(body)

        let (data, _) = try await session.data(for: request)
        let decoded = try decoder.decode(LivenessResponse.self, from: data)
        return decoded.data
    }
}

Quando a captura finalizar, o resultado passivo (Data) pode ser convertido para Base64 e enviado para a API de Liveness:

extension ViewController: BCCFaceDelegate {
    func faceCaptureDidFinish(
        data: BCCFace.BCCFaceReturnData,
        analytics: BCCFace.BCCFaceAnalytics
    ) {
        print("Capture finished")

        guard let passiveResult = data.passiveResult else {
            print("No passive result")
            return
        }
        print("Passive result received")
        
        Task {
            do {
                let bonafide = try await fetchBonafideScore(from: passiveResult)
                print("Bonafide Score: \(bonafide)")
            } catch {
                print("Error verifying liveness: \(error)")
            }
        }
    }

    func faceCaptureDidAbort(analytics: BCCFaceAnalytics) {
        print("Capture aborted")
    }
}

extension ViewController {
    /// Makes a request to the API service and returns the bonafide score
    func fetchBonafideScore(from passiveData: Data) async throws -> Int {
        let service = LivenessService(baseURL: Constants.API.baseURL)
        let credentials = Credentials(
            username: Constants.API.username,
            password: Constants.API.password
        )

        let token = try await service.getToken(using: credentials)
        let base64Result = passiveData.base64EncodedString()
        let result = try await service.checkLiveness(
            passiveResultInBase64: base64Result,
            bearer: token
        )

        return result.bonafideScore
    }
}

Atualizado há 4 meses

Isto foi útil?