Android

BCC Face é uma biblioteca Android destinada a ser integrada a um aplicativo Android.

Utiliza a câmera do dispositivo para tirar uma foto de um rosto para fins biométricos. Fornece um simples teste de vivacidade ativo, exigindo que a pessoa sorria por cerca de um segundo e/ou olhe para a direita ou esquerda. O teste de vivacidade inclui uma opção para reproduzir as instruções por voz, facilitando o fluxo para os usuários. Além disso, fornece um teste de vivacidade passivo que pode ser usado para verificar se a foto foi tirada de uma pessoa real sem exigir interação do usuário.

Este manual está atualizado para a versão BCC Face Mobile Android 4.8.0.

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

Requisitos

BCC Face é uma biblioteca Android e deve ser importada para o projeto alvo.

• Versão mínima do Android: Android 6.0 (SDK 23), "Marshmallow".

• O dispositivo móvel deve possuir câmera.

• O aplicativo nativo deve ser construído com tecnologia Android.

• Ambiente de desenvolvimento: é necessário um IDE Android, como Android Studio (recomendado).

• Dependências externas adicionais:

  • Google ML Kit, detecção facial versão 16.0.2;

  • Lottie, versão 3.0.0;

  • Libyuv-android, versão 1.0.0;

• Serviços externos:

  • Firebase, do Google. É necessária uma conta, mas não serão aplicadas cobranças já que a biblioteca usa apenas APIs no dispositivo.

Instalação

Adicionando a Biblioteca no Projeto do App

BCC Face é fornecido pela Griaule como um .aar arquivo.

Para adicionar as bibliotecas, vá até o diretório do seu projeto, abra a pasta app e crie os diretórios: libs/bccface. Em seguida, adicione a dependência bccfacelib-release.aar A estrutura de pastas deve ser similar a esta:

O próximo passo é tornar esses arquivos visíveis às dependências do gradle. Para isso, adicione a seguinte linha no arquivo build.gradle (:app), no objeto dependencies:

dependencies {
	[...]
	implementation fileTree(dir: 'libs/bccface', include: ['*.aar'])
}

Dentro do build.gradle (:app) arquivo, também adicione as opções de compilação e defina Source Compatibility e Target Compatibility para usar 1.8 (Java 8):

compileOptions {
	sourceCompatibility = 1.8
	targetCompatibility = 1.8
}

Configurando o Google ML Kit

Recomenda-se seguir as instruções fornecidas em "Opção 1: Use o fluxo de configuração do console do Firebase" da documentação do Firebase para Android: Adicionar o Firebase ao seu projeto Android.

É necessária uma conta, mas não serão aplicadas cobranças já que a biblioteca usa apenas APIs no dispositivo: Veja detalhes de preços do Firebase.

Se Opção 1 foi escolhida, certifique-se de gerar o arquivo google-services.json e colocá-lo em android/app/ diretório.

Faça alterações nos seguintes arquivos:

• android/build.gradle

  buildscript {
  	// ...
  	dependencies {
  		// ...
  		classpath 'com.google.gms:google-services:4.3.3'
  	}
  }

• android/app/build.gradle, adicione ao final do arquivo:

  // ...
  
  apply plugin: 'com.android.application'
  apply plugin: 'kotlin-android'
  apply plugin: 'kotlin-kapt'
  apply plugin: 'com.google.gms.google-services'
  
  // ...
  
  android {
  	// ...
  	buildFeatures {
  		viewBinding = true
  		dataBinding = true
  	}
  }
  
  // ...
  
  dependencies {
  	// ...
  	implementation 'com.google.firebase:firebase-analytics:17.2.2'
  	// Adicione a linha acima se usar analytics
  }

Configurando todas as dependências

Faça alterações nos seguintes arquivos:

• android/build.gradle

  allprojects {
  	repositories {
  		// ...
  		google()
  		mavenCentral()
  		maven { url 'https://jitpack.io' }
  	}
  }

• android/app/build.gradle

  // ...
  dependencies {
  	// ...
  	implementation project(path: ':bccfacelib')
  
  	// ANDROIDX //
  	implementation 'androidx.appcompat:appcompat:1.4.2'
  	implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
  	implementation 'com.google.android.material:material:1.6.1'
  
  	// Google MLKIT //
  	implementation 'com.google.mlkit:face-detection:16.0.2'
  
  	// LOTTIE //
  	implementation 'com.airbnb.android:lottie:3.0.0'
  
  	// LIBYUV //
  	implementation 'com.github.xiaoxiaoqingyi:libyuv-android:v1.0'
  
  	// CAMERA X //
  	def camerax_version = "1.2.0-rc01"
  	// Biblioteca core do CameraX usando implementação camera2
  	implementation "androidx.camera:camera-camera2:$camerax_version"
  	// Biblioteca Lifecycle do CameraX
  	implementation "androidx.camera:camera-lifecycle:$camerax_version"
  	// Classe View do CameraX
  	implementation "androidx.camera:camera-view:$camerax_version"
  }

Uso

Parâmetros e Construtor

Para usar corretamente a biblioteca BCC Face, existem alguns parâmetros obrigatórios.

Um exemplo simples de uso da biblioteca é mostrado abaixo:

BCCFaceBuilder(this, this).initializeCapture()

---

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

• context: Context - O contexto da aplicação.

• delegate: BCCFaceDelegate - Interface responsável por notificar eventos de captura (por exemplo, falha ou sucesso).

---

O BCCFaceBuilder a classe é responsável por controlar a configuração de uso para BCCFace. Os seguintes parâmetros são aceitos para configurar a captura biométrica e o comportamento do software:

• buildSmileCheck(smileProbability: Float = 0.8f) - Adiciona o sorriso para o teste de vivacidade e define o limiar de aceitação. Este recurso está habilitado por padrão.

• removeSmileCheck() - Remove o sorriso do teste de vivacidade.

• buildRotationCheck(livenessConfigList: List<HeadRotationCheck>, headRotationAngle: Float = 20f) - Define uma lista de testes de vivacidade para rotação da cabeça e ângulo máximo de rotação. Este recurso está habilitado por padrão. As opções de rotação da cabeça são:

  enum class HeadRotationCheck {
  	randomRotation,
  	leftRotation,
  	rightRotation;
  }

• removeHeadRotation() - Remove a rotação da cabeça do teste de vivacidade.

• addPassiveLiveness() - Adiciona o teste de vivacidade passivo. Este recurso é usado para verificar se a foto capturada é de uma pessoa real sem exigir qualquer interação do usuário. Para usar este recurso, 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 fala de acessibilidade, usando os seguintes parâmetros:

  class SpeechSettings(
  	val volume: Float = 1.0f,
  	val startsMuted: Boolean = true,
  	val pitch: Float = 1.0f,
  	val speed: Float = 1.0f
  )

  • 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 timbre/altura da voz para as instruções entre 0.5 (baixo) e 2.0 (alto).

  • speed - Define a velocidade da voz para as instruções. Este valor deve ser positivo.

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

  class SpeechSettings {
  	companion object {
  		val defaultSpeechSettings = SpeechSettings()
  	}
  }

• removeSpeech() - Remove a fala de acessibilidade.

• setReviewEnable(enable: Boolean) - Define se a tela de revisão da captura biométrica está habilitada ou desabilitada.

• setInstructionEnable(enable: Boolean) - Define se a tela de instruções está habilitada ou desabilitada.

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

  enum class BCCLanguages(val locale: Locale) {
  	ptBR(Locale("pt", "br")),
  	enUS(Locale.US),
  	esMX(Locale("es", "mx")),
  	deviceLanguage(Locale.getDefault());
  }

• removeLanguage() - Remove o idioma forçado.

• enableFlipCameraButton(enable: Boolean) - Ativa (true) ou desativa (false) o botão de alternância da câmera (câmera frontal ou traseira). Padrão: habilitado (true).

• setCameraInitialDirection(CameraFacingDirection.<FRONT or BACK>) - Define a direção inicial da câmera, escolha entre:

  • CameraFacingDirection.FRONT - Câmera frontal (configuração padrão).

  • CameraFacingDirection.BACK - Câmera traseira.

---

Todas as configurações de direção da câmera são obtidas através da combinação dos métodos enableFlipCameraButton e setCameraInitialDirection Por exemplo:

• Começar com a câmera frontal e habilitar o botão de alternância da câmera:

  BCCFaceBuilder(this, this)
  	.enableFlipCameraButton(true)
  	.setCameraInitialDirection(CameraFacingDirection.FRONT)

• Começar com a câmera traseira e desabilitar o botão de alternância da câmera:

  BCCFaceBuilder(this, this)
  	.enableFlipCameraButton(false)
  	.setCameraInitialDirection(CameraFacingDirection.BACK)

---

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

var showPhotoReview: Boolean = false,
var showInstructionScreen: Boolean = false,
var stopVerifyEyesOpenTimeout: Long = 20,
var useICAO: Boolean = false,
var smilingProbabilityThreshold: Float = 0.8f,
var rotateAngle: Float = 20f,
var livenessList: MutableList<LivenessTypes> = mutableListOf(LivenessTypes.SMILE, LivenessTypes.ROTATION_RANDOM),
var language: BCCFaceAPI.BCCLanguages? = null,
var speechSettings: SpeechSettings? = SpeechSettings(),
var activityResults: FaceCaptureActivityResults? = null

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

BCCFaceBuilder(this, this)
	.removeSmileCheck()
	.removeHeadRotation()
	.addPassiveLiveness()

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

// A partir da Activity desejada...

// Crie o builder
BCCFaceBuilder faceBuilder = new BCCFaceBuilder(this, this);

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

// Inicialize a captura a partir do builder
faceBuilder.initializeCapture();

Valores de Retorno

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

fun faceCaptureDidFinish(
	data: BCCFaceReturnData,
	analytics: BCCFaceReturnAnalytics
)

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

class BCCFaceReturnData {
	val originalPhoto: Bitmap?
	val croppedPhoto: Bitmap?

	// Resultado da Vivacidade Passiva
	val passiveResult: ByteArray?
}

As propriedades retornadas são:

• originalPhoto (imagem) - A foto original tirada pela câmera.

• croppedPhoto (imagem) - A foto recortada, que é a imagem do rosto recortada da foto original.

• passiveResult (ByteArray) - Conteúdo do arquivo da coleta para vivacidade passiva. Está presente apenas se capturado com sucesso. É o retorno da coleta para vivacidade passiva como JPEG ByteArray. Esses dados podem ser salvos/exportados diretamente para um arquivo ou enviados pela rede (para envio em rede: a codificação do sistema pode ser facilmente feita, por exemplo, string Base64).

O originalPhoto e croppedPhoto propriedades retornam null quando a captura é realizada apenas para testes passivos (ou seja, sem incluir um teste ativo).

Se o usuário abortar a captura, fechando antes de capturar a biometria, o método faceCaptureDidAbort será chamado. Você pode implementar esse método para tratar esse cenário.

Projeto de Exemplo

Este é um projeto de exemplo funcional para captura de rosto usando BCC Mobile Face Android:

package com.example.bccfaceexample

import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.example.bccfaceexample.databinding.ActivityMainBinding
import com.griaule.bccfacelib.analytics.BCCFaceReturnAnalytics
import com.griaule.bccfacelib.faceApi.BCCFaceBuilder
import com.griaule.bccfacelib.faceApi.BCCFaceDelegate
import com.griaule.bccfacelib.faceApi.BCCFaceReturnData

class MainActivity : AppCompatActivity(), BCCFaceDelegate {
	private lateinit var binding: ActivityMainBinding

	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)
		binding = ActivityMainBinding.inflate(layoutInflater)
		setContentView(binding.root)
		setupListeners()
	}

	private fun setupListeners() {
		binding.startCaptureButton.setOnClickListener { initializeCapture() }
	}

	private fun initializeCapture() {
		BCCFaceBuilder(this, this)
			.removeSmileCheck()
			.removeHeadRotation()
			.addPassiveLiveness()
			.enableFlipCameraButton(true)
			.enableFlashButton(true)
			.initializeCapture()
	}

	override fun faceCaptureDidFinish(
		data: BCCFaceReturnData,
		analytics: BCCFaceReturnAnalytics
	) {
		// ...
	}

	override fun faceCaptureDidAbort(
		analytics: BCCFaceReturnAnalytics
	) {
		// ...
	}
}