1. Introdução¶

A BCC Finger é um biblioteca feita para ser integrada em uma aplicação iOS por um arquivo .framework. Ela usa a câmera do dispositivo para tirar fotos das digitais para propósitos biométricos.

Esse manual está atualizado para a versão 4.3.0 da BCC Finger Photo iOS.

1.1. Requisitos¶

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

2. Installation¶

2.1. Installing Dependencies¶

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

pod 'lottie-ios'

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:

target 'BCCs-Sample' do
  use_frameworks!

  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['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
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.

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.

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 FingerPhoto.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 BCCFinger.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 personalizada.

3. Uso¶

3.1. Parâmetros e Construtor¶

Um uso simples da biblioteca é mostrado abaixo:

// To initialize a new capture
BCCFingerBuilder(self, delegate: self).initializeCapture()

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

hostVC: UIViewController - View controller que chama a tela de captura.
delegate: BCCFingerDelegate - 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 BCCFingerBuilder é responsável por gerenciar as configurações de uso do BCCFinger. Os parâmetros a seguir são aceitos para confiuração da captura biométrica e comportamento do software.

setSkipCaptureOption(_ enable: Bool) - Habilita a opção de pular a captura atual.
setDebugMode(_ enable: Bool) - Habilita o modo de debug.
buildCaptures(_ captures: BCCFingerCaptureType) - Define o tipo de captura de impressão digital. As opções são:
```
public enum BCCFingerCaptureType {
    case BOTH_HANDS
    case ONLY_LEFT_HAND
    case ONLY_RIGHT_HAND
    case THUMBS
    case LEFT_THUMB
    case RIGHT_THUMB
    case FULL_HANDS
    case FULL_LEFT_HAND
    case FULL_RIGHT_HAND
}
```
- BOTH_HANDS - Ambas as mãos sem polegares.
- ONLY_LEFT_HAND - Somente a mão esquerda, sem polegar.
- ONLY_RIGHT_HAND - Somente a mão direita, sem polegar.
- THUMBS - Ambos os polegares.
- LEFT_THUMB - Somente polegar esquerdo.
- RIGHT_THUMB - Somente polegar direito.
- FULL_HANDS - Ambas as mãos com polegares.
- FULL_LEFT_HAND - Somente a mão esquerda, com polegar.
- FULL_RIGHT_HAND - Somente a mão direita, com polegar.
buildBeginDelaySeconds(_ delay: Float) - Define o delay para inciiar o ajuste automático do limiar.
buildThreshold - Define os parâmetros de limiar.

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

var skipsHandOption: Bool = false
var debugMode: Bool = false
var capture: BCCFingerCaptureType = .FULL_HANDS
var beginDelaySeconds: Float = 1
var minQuality: Int = 20
var maxQuality: Int = 80
var totalTime: Double = 30
var stepCount: Int = 30

3.2. Valores de Retorno¶

Os resultados da última captura de impressão digital podem ser recuperados através do método fingerCaptureDidFinish da interface BCCFingerDelegate:

func fingerCaptureDidFinish(
    _ returnData: BCCFingerReturnData,
    analytics: BCCFingerAnalytics
)

O objeto returnData contém os seguintes métodos para recuperação dos dados:

getCapturedFingersIndexes() - Retorna uma lista com o índice de todas as impressões digitais capturadas:

public enum FingerIndex: Int {
    case leftLittle = 0
    case leftRing = 1
    case leftMiddle = 2
    case leftIndex = 3
    case leftThumb = 4
    case rightThumb = 5
    case rightIndex = 6
    case rightMiddle = 7
    case rightRing = 8
    case rightLittle = 9
}

getCapturedFingers() - Retorna um mapa que relaciona os índices dos dedos com as biometrias capturadas.
getCapturedFingersData() - Retorna a lista de todas as impressões digitais capturadas:
```
public var fingerprintPNG: UIImage
public var wsqAsBase64: String
```
- fingerprintImage - Imagem PNG da impressão digital em escala de cinza.
- wsqAsBase64 - Imagem da impressão digital em WSQ codificada em base64.
getSkippedFingers() - Retorna a lista de índices das capturas puladas.

A classe BCCFingerReturnData também contém atributos que armazenam a informação capturada agrupada por mão:

public class BCCFingerReturnData {
    public let leftHand: HandData?
    public let rightHand: HandData?
}

Estes atributos podem ser nulos nos casos em não seja requerida captura para qualquer uma das mãos.

A classe HandData contém as seguintes informações:

public internal(set) var capturedFingers: [FingerIndex : FingerData] = [:]
public internal(set) var skippedFingers: [FingerIndex] = []
public internal(set) var handsPhoto: UIImage? = nil
public internal(set) var thumbsPhoto: UIImage? = nil

capturedFingers - Mapa que relaciona o índice do dedo à imagem da impressão digital.
skippedFingers - Lista de índices das capturas puladas.
handsPhoto - Foto original da mão que gerou as impressões digitais.
thumbPhoto - Foto original do polegar.

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

3.2.1. Recuperando as imagens originais¶

É possível recuperar as imgens originais através da classe BCCFingerReturnData, conforme mostrado abaixo:

let leftSlapPhoto = returnData.leftHand?.handsPhoto
let rightSlapPhoto = returnData.rightHand?.handsPhoto
let leftThumbPhoto = returnData.leftHand?.thumbsPhoto
let rightThumbPhoto = returnData.rightHand?.handsPhoto

3.3. Projeto Exemplo¶

Este é um exemplo de projeto funcional para captura de impressões digitais utilizando o BCC Finger iOS:

import UIKit
import FingerPhoto
import BCCFinger

class ViewController: UIViewController {

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

    @IBAction func startCaptureAction(_ sender: UIButton) {
        BCCFingerBuilder(self, delegate: self)
            .initializeCapture()
    }
}

extension ViewController: BCCFingerDelegate {

    func fingerCaptureDidFinish(
        _ returnData: BCCFinger.BCCFingerReturnData,
        analytics: BCCFinger.BCCFingerAnalytics
    ) {
        // ...
    }

    func didAbortFingerCapture(
        analytics: BCCFinger.BCCFingerAnalytics
    ) {
        // ...
    }

}