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.

O teste de vivacidade passiva está disponível apenas a partir da versão 4.4.0 em diante.

Requisitos

• Git

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

Instalação

Instalando Dependências

1 - Adicione os seguintes Pods às dependências da aplicação no Podfile:

pod 'lottie-ios'

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.

É 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:

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

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.

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.

2 - Feche o projeto Xcode, abra um terminal, vá para a pasta onde o Podfile está localizado e, em seguida, execute:

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.

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.

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.

É recomendado desativar o iPad como target.

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:

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:

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:

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<Float> = 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<Float> = -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:

  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:

  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:

  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:

  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:

var headRotationAngle: ClosedRange<Float> = -6.0...6.0
var openEyesProbability: ClosedRange<Float> = 0.8...1.1  // Obsoleto desde 4.12.2
var smileProbability: ClosedRange<Float> = 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

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:

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

Aqui está um snippet de código para inicializar uma captura usando apenas o teste de vivacidade passiva:

// 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 :

func faceCaptureDidFinish(
	data: BCCFaceReturnData,
	analytics: BCCFaceReturnAnalytics
)

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

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:

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