> 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/es/bcc-face/bccmobilefaceandroid.md). # Android ## Android **BCC Face** es una biblioteca de Android destinada a integrarse en una aplicación de Android. Utiliza la cámara del dispositivo para tomar una foto de un rostro con fines biométricos. Proporciona una sencilla prueba activa de vitalidad, que requiere que la persona sonría durante aproximadamente un segundo y/o mire a la derecha o a la izquierda. La prueba de vitalidad incluye la opción de reproducir las instrucciones por voz, lo que facilita el flujo para los usuarios. Además, proporciona una prueba pasiva de vitalidad que puede usarse para verificar que la foto se tomó de una persona real sin requerir interacción del usuario. Este manual está actualizado para la versión de BCC Face Mobile Android `4.12.2`. {% hint style="warning" %} La **prueba pasiva de vitalidad** está disponible solo a partir de la versión `4.4.0` en adelante. {% endhint %} ### Requisitos **BCC Face** es una biblioteca de Android y debe importarse en el proyecto de destino. * Versión mínima de Android: *Android 6.0 (SDK 23), "Marshmallow"*. * El dispositivo móvil debe tener una cámara. * La aplicación nativa debe estar desarrollada con tecnología Android. * Entorno de desarrollo: se requiere un IDE de Android, como [Android Studio](https://developer.android.com/studio) (recomendado). * Dependencias externas adicionales: * [Google ML Kit](https://developers.google.com/ml-kit/guides), versión de detección facial 16.1.7; * [Lottie](https://lottiefiles.com), versión 3.0.0; * [RootBeer](https://github.com/scottyab/rootbeer), versión 0.1.1; * [Gson](https://github.com/google/gson), versión 2.8.5; * [Google Tink](https://github.com/tink-crypto), versión 1.11.0; * [Material Components](https://github.com/material-components/material-components-android), versión 1.6.1. * Servicios externos: * Firebase, de Google. Se requiere una cuenta, pero no se aplicarán cargos, ya que la biblioteca solo usa APIs en el dispositivo. ### Instalación #### Agregar la biblioteca al proyecto de la aplicación BCC Face es proporcionado por Griaule como un `.aar` archivo. Para agregar las bibliotecas, vaya al directorio de su proyecto, abra la carpeta **app** y cree los directorios: `libs/bccface`. Luego agregue la dependencia `bccfacelib-release.aar` . La estructura de carpetas debería verse similar a esta: ![](https://3411546999-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5TVzatVMAV3OF5tyA1VF%2Fuploads%2Fgit-blob-c549379fb9b16f47f9db997405fe4476d8ed1014%2FfaceFolderStructre.png?alt=media) El siguiente paso es hacer visibles estos archivos para las dependencias de Gradle. Para ello, agregue la siguiente línea al archivo `build.gradle (:app)` , dentro del objeto dependencies: ```groovy dependencies { [...] implementation fileTree(dir: 'libs/bccface', include: ['*.aar']) } ``` Dentro del archivo `build.gradle (:app)` , agregue también las opciones de compilación y establezca Source Compatibility y Target Compatibility para usar 1.8 (Java 8): ```groovy compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } ``` #### Configuración de Google ML Kit Se recomienda seguir las instrucciones proporcionadas en "[Opción 1: use el flujo de configuración de la consola de Firebase](https://firebase.google.com/docs/android/setup#console)" de la documentación de Firebase para Android: [Agregue Firebase a su proyecto de Android](https://firebase.google.com/docs/android/setup). Se requiere una cuenta, pero no se aplicarán cargos, ya que la biblioteca solo usa APIs en el dispositivo: [Ver detalles de precios de Firebase](https://firebase.google.com/pricing/). Si [se eligió la Opción 1,](https://firebase.google.com/docs/android/setup#console) asegúrese de generar el archivo `google-services.json` y colocarlo en el directorio `android/app/` . Realice cambios en los siguientes archivos: * `android/build.gradle` ```groovy buildscript { // ... dependencies { // ... classpath 'com.google.gms:google-services:4.4.2' } } ``` * `android/app/build.gradle`, agregue al final del archivo: ```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' // Agregue la línea anterior si usa analytics } ``` #### Configuración de todas las dependencias Realice cambios en los siguientes archivos: * `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 y constructor Para usar correctamente la biblioteca BCC Face, hay algunos parámetros obligatorios. A continuación se muestra un ejemplo sencillo de uso de la biblioteca: ```kotlin BCCFaceBuilder(this, this).initializeCapture() ``` *** `BCCFaceBuilder` es el constructor de la clase y recibe los siguientes parámetros: * `context: Context` - El contexto de la aplicación. * `delegate: BCCFaceDelegate` - Interfaz responsable de notificar eventos de captura (por ejemplo, fallo o éxito). *** `BCCFaceBuilder` es la clase responsable de controlar la configuración de uso de `BCCFace`. Se aceptan los siguientes parámetros para configurar la captura biométrica y el comportamiento del software: * `buildSmileCheck(smileProbability: Float = 0.8f)` - Añade la sonrisa a la prueba de vitalidad y establece el umbral de aceptación. Esta función está habilitada de forma predeterminada. * `removeSmileCheck()` - Elimina la sonrisa de la prueba de vitalidad. * `buildRotationCheck(livenessConfigList: List, headRotationAngle: Float = 20f)` - Define una lista de pruebas de vitalidad de rotación de cabeza y el ángulo máximo de rotación. Esta función está habilitada de forma predeterminada. Las opciones de rotación de cabeza son: ```kotlin enum class HeadRotationCheck { randomRotation, leftRotation, rightRotation; } ``` * `removeHeadRotation()` - Elimina la rotación de cabeza de la prueba de vitalidad. * `addPassiveLiveness()` - Añade la prueba pasiva de vitalidad. Esta función se usa para verificar que la foto capturada sea de una persona real sin requerir ninguna interacción del usuario. Para usar solo esta función, deben deshabilitarse las pruebas activas de vitalidad (`removeSmileCheck()` y `removeHeadRotation()`), que están habilitadas de forma predeterminada. También es posible combinar ambos tipos de prueba, usando vitalidad pasiva y activa simultáneamente. * `buildSpeechSettings(speechSettings: SpeechSettings?)` - Define los criterios para el discurso de accesibilidad, usando los siguientes 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` - El volumen de audio entre `0.0` y `1.0`. * `startsMuted` - Define si las instrucciones comienzan silenciadas o no (`true` para silenciado). * `pitch` - Define el tono de voz de las instrucciones entre `0.5` (grave) y `2.0` (agudo). * `speed` - Define la velocidad de la voz de las instrucciones. Este valor debe ser positivo. Los valores predefinidos pueden accederse a través de la variable estática: ```groovy class SpeechSettings { companion object { val defaultSpeechSettings = SpeechSettings() } } ``` * `removeSpeech()` - Elimina la voz de accesibilidad. * `setInstructionEnable(enable: Boolean)` - Define si la pantalla de instrucciones está habilitada o deshabilitada. * `forceLanguage(language: BCCFaceAPI.BCCLanguages?)` - Fuerza que las instrucciones se muestren en un solo idioma. Si el idioma del dispositivo no es compatible, se usará inglés. Los idiomas compatibles son: ```kotlin enum class BCCLanguages(val locale: Locale) { ptBR(Locale("pt", "br")), enUS(Locale.US), esMX(Locale("es", "mx")), deviceLanguage(Locale.getDefault()); } ``` * `removeLanguage()` - Elimina el idioma forzado. * `enableFlipCameraButton(enable: Boolean)` - Habilita (`true`) o deshabilita (`false`) el botón para cambiar la cámara (cámara frontal o trasera). Valor predeterminado: habilitado (`true`). * `enableFlashButton(enable: Boolean)` - Habilita (`true`) o deshabilita (`false`) el botón de flash en la cámara trasera. Valor predeterminado: deshabilitado (`false`). * `enableManualCapture(enable: Boolean)` - Habilita (`true`) o deshabilita (`false`) el botón de captura manual, que permite omitir las comprobaciones automáticas de captura. Al realizar una captura manual, el usuario podrá revisar la foto capturada antes de finalizar el proceso. * `enableIntegrityValidation(clientSecret: ByteArray, nonce: ByteArray)` - Habilita la validación de integridad para la vitalidad pasiva, una capa adicional de seguridad para garantizar la integridad de la carga útil. * `setImageCompressionFormat(format: ImageCompressionFormat)` - Define el formato de compresión de una captura de vitalidad pasiva. Puede elegir entre `ImageCompressionFormat.JPEG` (predeterminado) o `ImageCompressionFormat.JPEG200` * `setCameraInitialDirection(CameraFacingDirection.)` - Define la dirección inicial de la cámara; elija entre: * `CameraFacingDirection.FRONT` - Cámara frontal (configuración predeterminada). * `CameraFacingDirection.BACK` - Cámara trasera. *** Todas las configuraciones de dirección de la cámara se logran combinando los métodos `enableFlipCameraButton` y `setCameraInitialDirection` . Por ejemplo: * Comience con la cámara frontal y habilite el botón para cambiar la cámara: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(true) .setCameraInitialDirection(CameraFacingDirection.FRONT) ``` * Comience con la cámara trasera y deshabilite el botón para cambiar la cámara: ```kotlin BCCFaceBuilder(this, this) .enableFlipCameraButton(false) .setCameraInitialDirection(CameraFacingDirection.BACK) ``` *** Como referencia, aquí está la lista completa de parámetros y valores predeterminados: ```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" %} La prueba activa de vitalidad (usando sonrisa y rotación aleatoria de la cabeza) está habilitada de forma predeterminada. Para usar solo la prueba pasiva de vitalidad, antes de agregarla, debe eliminar los métodos de vitalidad activa del generador: ```kotlin BCCFaceBuilder(this, this) .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness() ``` {% endhint %} Aquí hay un fragmento de código para inicializar una captura usando solo la prueba pasiva de vitalidad: ```kotlin // Desde la Activity deseada... // Cree el generador BCCFaceBuilder faceBuilder = new BCCFaceBuilder(this, this); // Configure el generador faceBuilder .removeSmileCheck() .removeHeadRotation() .addPassiveLiveness(); // Inicialice la captura desde el generador faceBuilder.initializeCapture(); ``` #### Valores de retorno Los resultados de la última captura facial se pueden recuperar usando el método `faceCaptureDidFinish` de la interfaz `BCCFaceDelegate` : ```kotlin fun faceCaptureDidFinish( data: BCCFaceReturnData, analytics: BCCFaceReturnAnalytics ) ``` La `data` contiene ambas imágenes capturadas durante el proceso: ```kotlin class BCCFaceReturnData { val originalPhoto: Bitmap? val croppedPhoto: Bitmap? // Resultado de la vitalidad pasiva val passiveResult: ByteArray? } ``` Las propiedades devueltas son: * `originalPhoto` (*imagen*) - La foto original tomada por la cámara. * `croppedPhoto` (*imagen*) - La foto recortada, que es la imagen del rostro recortada de la foto original. * `passiveResult` (*ByteArray*) - Contenido del archivo de la colección de vitalidad pasiva. Solo está presente si se capturó correctamente. Es la devolución de la colección de vitalidad pasiva como un *ByteArray JPEG* o *JPEG 2000*. Estos datos pueden guardarse/exportarse directamente a un archivo o enviarse por la red (para la transmisión por red, los datos pueden codificarse fácilmente, por ejemplo, como una cadena Base64). {% hint style="info" %} La `originalPhoto` y `croppedPhoto` Estas propiedades devuelven `null` cuando la captura se realiza solo para pruebas pasivas (es decir, sin incluir una prueba activa). {% endhint %} Si el usuario cancela la captura o si ocurre algún fallo durante el proceso, se llamará al método `faceCaptureDidAbort` . Puede implementar este método para manejar este escenario. #### Proyecto de ejemplo Este es un proyecto de ejemplo funcional para la 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/es/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.