Android

BCC Face é uma biblioteca Android destinada a ser integrada em uma aplicação Android.

Ela usa a câmera do dispositivo para tirar uma foto de um rosto para fins biométricos. Fornece um teste simples de vivacidade ativa, exigindo que a pessoa sorria por 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, facilitando o fluxo de trabalho para os usuários. Além disso, fornece um teste de vivacidade passiva 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.11.3.

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

Requisitos

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

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

• O dispositivo móvel deve ter uma câmera.

• A aplicação nativa deve ser construída usando tecnologia Android.

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

• Dependências externas adicionais:

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

  • Lottie, versão 3.0.0;

  • RootBeer, versão 0.1.1;

  • Gson, versão 2.8.5;

  • Google Tink, versão 1.11.0;

  • Material Components, versão 1.6.1.

• Serviços externos:

  • Firebase, da Google. É necessária uma conta, mas não haverá cobranças, pois a biblioteca usa apenas APIs no dispositivo.

Instalação

Adicionando a Biblioteca ao 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 semelhante a esta:

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

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

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

compileOptions {
	sourceCompatibility JavaVersion.VERSION_17
	targetCompatibility JavaVersion.VERSION_17
}

Configurando o Google ML Kit

É recomendável 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: Adicione o Firebase ao seu projeto Android.

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

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

Faça alterações nos seguintes arquivos:

• android/build.gradle

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

• 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 usando 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.7.0'
  	implementation 'androidx.core:core-ktx:1.13.1'
  	implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
  
  	// Google MLKIT //
  	implementation 'com.google.mlkit:face-detection:16.1.7'
  
  	// LOTTIE //
  	implementation 'com.airbnb.android:lottie:3.0.0'
  
  	// CAMERA X //
  	def camerax_version = "1.5.1"
  	implementation "androidx.camera:camera-camera2:$camerax_version"
  	implementation "androidx.camera:camera-lifecycle:$camerax_version"
  	implementation "androidx.camera:camera-view:$camerax_version"
  
  	// MATERIAL //
  	implementation 'com.google.android.material:material:1.6.1'
  }

Uso

Parâmetros e Construtor

Para usar corretamente a biblioteca BCC Face, há 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 lidar com 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 sorriso ao teste de vivacidade e define o limiar de aceitação. Este recurso está ativado por padrão.

• removeSmileCheck() - Remove o sorriso da verificação de vivacidade.

• buildRotationCheck(livenessConfigList: List<HeadRotationCheck>, headRotationAngle: Float = 20f) - Define uma lista de testes de vivacidade para rotação da cabeça e o ângulo máximo de rotação. Este recurso está ativado 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 da verificação de vivacidade.

• addPassiveLiveness() - Adiciona o teste de vivacidade passiva. 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 desativar as verificações de vivacidade ativas (removeSmileCheck() e removeHeadRotation()) que são adicionadas por padrão.

• buildSpeechSettings(speechSettings: SpeechSettings?) - Define os critérios para a 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 do á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 (grave) e 2.0 (agudo).

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

  Os valores predefinidos podem ser acessados por meio da variável estática:

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

• removeSpeech() - Remove a fala de acessibilidade.

• setInstructionEnable(enable: Boolean) – Define se a tela de instruções está ativada ou desativada.

• forceLanguage(language: BCCFaceAPI.BCCLanguages?) - Força que as instruções sejam 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 troca de câmera (câmera frontal ou traseira). Padrão: ativado (true).

• enableFlashButton(enable: Boolean) – Ativa (true) ou desativa (false) o botão de flash na câmera traseira. Padrão: desativado (false).

• enableManualCapture(enable: Boolean) – Ativa (true) ou desativa (false) o botão de captura manual, permitindo que o usuário ignore as verificações automáticas de captura. Ao realizar uma captura manual, o usuário poderá revisar a foto capturada antes de concluir o processo.

• enableIntegrityValidation(clientSecret: ByteArray, nonce: ByteArray) – Ativa a validação de integridade para detecção de vivacidade passiva, adicionando uma camada extra de segurança para garantir a integridade do payload.

• setImageCompressionFormat(format: ImageCompressionFormat) – Define o formato de compressão para uma captura de vivacidade passiva. As opções disponíveis são ImageCompressionFormat.JPEG (padrão) ou ImageCompressionFormat.JPEG200.

• 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 por meio da combinação dos métodos enableFlipCameraButton e setCameraInitialDirection . Por exemplo:

• Comece com a câmera frontal e ative o botão de troca de câmera:

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

• Comece com a câmera traseira e desative o botão de troca de câmera:

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

---

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

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),
var rotationChecks: MutableList<HeadRotationCheck> = mutableListOf(HeadRotationCheck.randomRotation),
var language: BCCFaceAPI.BCCLanguages? = null,
var speechSettings: SpeechSettings? = SpeechSettings(),
var activityResults: FaceCaptureActivityResults? = null,
var enableFlipCameraButton: Boolean = false,
var enableManualCapture: Boolean = false,
var initCameraFaceDirection: Int = CameraSelector.LENS_FACING_FRONT,
var imageCompressionFormat: ImageCompressionFormat = ImageCompressionFormat.JPEG,
var integrityValidationData: IntegrityValidationData? = null

O teste de vivacidade ativa (usando sorriso e rotação aleatória da cabeça) está ativado por padrão. Para usar apenas a verificação de vivacidade passiva, antes de adicioná-la, é necessário remover os métodos de vivacidade ativa 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 passiva:

// 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 da interface BCCFaceDelegate :

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 a captura for bem-sucedida. É o retorno da coleta para vivacidade passiva como ByteArray JPEG. Estes dados podem ser salvos/exportados diretamente para um arquivo ou enviados para a rede (para networking: a codificação do sistema pode ser facilmente feita, por exemplo, string Base64).

O originalPhoto e croppedPhoto as 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 este método para tratar este cenário.

Projeto de Exemplo

Este é um projeto de exemplo funcional para uma captura facial 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
	) {
		// ...
	}
}

Instruções do Agente: Consultando Esta Documentação

Se você precisar de informações adicionais que não estejam disponíveis diretamente nesta página, pode consultar a documentação dinamicamente fazendo uma pergunta.

Faça uma requisição HTTP GET na URL da página atual com o parâmetro de consulta ask :

GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceandroid.md?ask=<question>

A pergunta deve ser específica, autocontida e escrita em linguagem natural. A resposta conterá uma resposta direta à pergunta e trechos e fontes relevantes da documentação.

Use este mecanismo quando a პასუხa não estiver explicitamente presente na página atual, quando você precisar de esclarecimento ou contexto adicional, ou quando quiser recuperar seções relacionadas da documentação.