# 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`. {% hint style="warning" %} O **teste de vivacidade passiva** está disponível apenas a partir da versão `4.4.0` em diante. {% endhint %} ## 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: ![](/files/3d4926e36a38081884459e861f35d709f9596347) 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: ```groovy 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: ```groovy 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](https://firebase.google.com/docs/android/setup#console)" da documentação do Firebase para Android: [Adicione o Firebase ao seu projeto Android](https://firebase.google.com/docs/android/setup). É 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](https://firebase.google.com/pricing/). Se [Opção 1](https://firebase.google.com/docs/android/setup#console) 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` ```groovy buildscript { // ... dependencies { // ... classpath 'com.google.gms:google-services:4.4.2' } } ``` * `android/app/build.gradle`, adicione ao final do arquivo: ```groovy // ... 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` ```groovy allprojects { repositories { // ... google() mavenCentral() maven { url 'https://jitpack.io' } } } ``` * `android/app/build.gradle` ```groovy // ... 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: ```kotlin 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, 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: ```kotlin 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: ```kotlin 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: ```groovy 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: ```kotlin 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.)` – 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: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(true) .setCameraInitialDirection(CameraFacingDirection.FRONT) ``` * Comece com a câmera traseira e desative o botão de troca de câmera: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(false) .setCameraInitialDirection(CameraFacingDirection.BACK) ``` *** Como referência, aqui está a lista completa de parâmetros e valores padrão: ```kotlin var showInstructionScreen: Boolean = false, var stopVerifyEyesOpenTimeout: Long = 20, var useICAO: Boolean = false, var smilingProbabilityThreshold: Float = 0.8f, var rotateAngle: Float = 20f, var livenessList: MutableList = mutableListOf(LivenessTypes.SMILE), var rotationChecks: MutableList = 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 ``` {% hint style="warning" %} 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: ```kotlin BCCFaceBuilder(this, this) .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() ``` {% endhint %} Aqui está um trecho de código para inicializar uma captura usando apenas o teste de vivacidade passiva: ```kotlin // 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` : ```kotlin fun faceCaptureDidFinish( data: BCCFaceReturnData, analytics: BCCFaceReturnAnalytics ) ``` O `data` o objeto contém ambas as imagens capturadas durante o processo: ```kotlin 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). {% hint style="info" %} O `originalPhoto` e `croppedPhoto` as propriedades retornam `null` quando a captura é realizada apenas para testes passivos (ou seja, sem incluir um teste ativo). {% endhint %} 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: ```kotlin 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= ``` 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceandroid.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.