> For the complete documentation index, see [llms.txt](https://docs.griaule.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.griaule.com/sdks/bcc-face/bccmobilefaceandroid.md). # Android **BCC Face** é uma biblioteca Android destinada a ser integrada numa aplicação Android. Utiliza a câmera do dispositivo para tirar uma foto do rosto para fins biométricos. Fornece um teste de vivacidade ativo simples, 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 reproduzir as instruções por voz, tornando o fluxo mais fácil para os utilizadores. 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 utilizador. Este manual está atualizado para a versão Android Mobile do BCC Face `4.12.2`. {% 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 com tecnologia Android. * Ambiente de desenvolvimento: é necessário um IDE Android, como [Android Studio](https://developer.android.com/studio) (recomendado). * Dependências externas adicionais: * [Google ML Kit](https://developers.google.com/ml-kit/guides), versão de deteção facial 16.1.7; * [Lottie](https://lottiefiles.com), versão 3.0.0; * [RootBeer](https://github.com/scottyab/rootbeer), versão 0.1.1; * [Gson](https://github.com/google/gson), versão 2.8.5; * [Google Tink](https://github.com/tink-crypto), versão 1.11.0; * [Componentes Material](https://github.com/material-components/material-components-android), versão 1.6.1. * Serviços externos: * Firebase, da Google. É necessária uma conta, mas não serão cobradas taxas, uma vez que a biblioteca usa apenas APIs no dispositivo. ### Instalação #### Adicionando a Biblioteca ao Projeto da Aplicação BCC Face é fornecido pela Griaule como um `.aar` arquivo. Para adicionar as bibliotecas, vá ao diretório do projeto, abra a pasta **app** e crie os diretórios: `libs/bccface`. Depois adicione a dependência `bccfacelib-release.aar` . A estrutura de pastas deve parecer-se com isto: ![](https://3411546999-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5TVzatVMAV3OF5tyA1VF%2Fuploads%2Fgit-blob-c549379fb9b16f47f9db997405fe4476d8ed1014%2FfaceFolderStructre.png?alt=media) O próximo passo é tornar estes ficheiros visíveis para as dependências do Gradle. Para isso, adicione a seguinte linha ao `build.gradle (:app)` arquivo, dentro do 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 a compatibilidade de origem e a compatibilidade de destino para usar 1.8 (Java 8): ```groovy compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } ``` #### Configurando o Google ML Kit Recomenda-se seguir as instruções fornecidas em "[Opção 1: Use o fluxo de configuração da consola Firebase](https://firebase.google.com/docs/android/setup#console)" na 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 cobradas taxas, uma vez que a biblioteca usa apenas APIs no dispositivo: [Ver detalhes de preços do Firebase](https://firebase.google.com/pricing/). Se [Opção 1](https://firebase.google.com/docs/android/setup#console) tiver sido escolhida, certifique-se de gerar o `google-services.json` arquivo e 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 se estiver a usar 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, existem alguns parâmetros obrigatórios. Abaixo é mostrado um exemplo simples de utilização da biblioteca: ```kotlin BCCFaceBuilder(this, this).initializeCapture() ``` *** `BCCFaceBuilder` é o construtor da classe e 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). *** `BCCFaceBuilder` é a classe responsável por controlar a configuração de uso do `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 ao teste de vivacidade e define o limiar de aceitação. Esta funcionalidade está ativada por padrão. * `removeSmileCheck()` - Remove o sorriso do teste de vivacidade. * `buildRotationCheck(livenessConfigList: List, headRotationAngle: Float = 20f)` - Define uma lista de testes de vivacidade de rotação da cabeça e o ângulo máximo de rotação. Esta funcionalidade está ativada 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 do teste de vivacidade. * `addPassiveLiveness()` - Adiciona o teste de vivacidade passiva. Esta funcionalidade é usada para verificar se a foto capturada é de uma pessoa real sem exigir qualquer interação do utilizador. Para usar apenas esta funcionalidade, os testes de vivacidade ativos (`removeSmileCheck()` e `removeHeadRotation()`), que estão ativados por padrão, devem ser desativados. Também é possível combinar ambos os tipos de teste, usando vivacidade passiva e ativa simultaneamente. * `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 de áudio entre `0.0` e `1.0`. * `startsMuted` - Define se as instruções começam silenciadas ou não (`true` para silenciadas). * `pitch` - Define a tonalidade da 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: ```groovy class SpeechSettings { companion object { val defaultSpeechSettings = SpeechSettings() } } ``` * `removeSpeech()` - Remove a fala de acessibilidade. * `setInstructionEnable(enable: Boolean)` - Define se o ecrã de instruções está ativado ou desativado. * `forceLanguage(language: BCCFaceAPI.BCCLanguages?)` - Força as instruções a serem exibidas num único idioma. Se o idioma do dispositivo não for suportado, será usado o inglês. 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 alternar câmera (câmera frontal ou traseira). Padrão: ativado (`true`). * `enableFlashButton(enable: Boolean)` - Ativa (`true`) ou desativa (`false`) o botão de flash da câmera traseira. Padrão: desativado (`false`). * `enableManualCapture(enable: Boolean)` - 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 foto capturada antes de concluir o processo. * `enableIntegrityValidation(clientSecret: ByteArray, nonce: ByteArray)` - Ativa a validação de integridade para a vivacidade passiva, uma camada extra de segurança para garantir a integridade da carga útil. * `setImageCompressionFormat(format: ImageCompressionFormat)` - Define o formato de compressão de uma captura de vivacidade passiva. Pode escolher entre `ImageCompressionFormat.JPEG` (padrão) ou `ImageCompressionFormat.JPEG200` * `setCameraInitialDirection(CameraFacingDirection.)` - Define a direção inicial da câmera; escolha entre: * `CameraFacingDirection.FRONT` - Câmera frontal (definição padrão). * `CameraFacingDirection.BACK` - Câmera traseira. *** Todas as configurações da direção da câmera são obtidas combinando os métodos `enableFlipCameraButton` e `setCameraInitialDirection` . Por exemplo: * Comece com a câmera frontal e ative o botão de alternar câmera: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(true) .setCameraInitialDirection(CameraFacingDirection.FRONT) ``` * Comece com a câmera traseira e desative o botão de alternar câmera: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(false) .setCameraInitialDirection(CameraFacingDirection.BACK) ``` *** Para referência, aqui está a lista completa de parâmetros e valores predefinidos: ```kotlin var showInstructionScreen: Boolean = false, var stopVerifyEyesOpenTimeout: Long = 20, // Obsoleto desde 4.12.2 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 ativo (usando sorriso e rotação aleatória da cabeça) está ativado por padrão. Para usar apenas o teste de vivacidade passiva, antes de o adicionar, deve 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 construtor BCCFaceBuilder faceBuilder = new BCCFaceBuilder(this, this); // Configure o construtor faceBuilder .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness(); // Inicialize a captura a partir do construtor faceBuilder.initializeCapture(); ``` #### Valores de Retorno Os resultados da última captura facial podem ser obtidos usando o `faceCaptureDidFinish` método da interface `BCCFaceDelegate` : ```kotlin fun faceCaptureDidFinish( data: BCCFaceReturnData, analytics: BCCFaceReturnAnalytics ) ``` O `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 ficheiro da recolha de vivacidade passiva. Só está presente se tiver sido capturado com sucesso. É o retorno da recolha de vivacidade passiva como um *ByteArray 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). {% 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 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 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 ) { // ... } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.griaule.com/sdks/bcc-face/bccmobilefaceandroid.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.