MÓDULO NATIVO

Grabadora de Video (Android)

Esta documentación proporciona una guía detallada para desarrolladores sobre cómo integrar e implementar el SDK Grabadora de Video de DICIO en aplicaciones Android utilizando Jetpack Compose. El SDK facilita la grabación de videos cortos (para prueba de vida, recolección de consentimiento, etc.) aplicando validaciones de tiempo y control de hardware de forma transparente.

Regresar

ANDROIDJETPACK COMPOSEv2.2.0

Compatibilidad y Requisitos

Lenguaje

Kotlin / Java

OS Min

Android 7+

API / Target

API 24+

IDE

Jellyfish+

1. Configuración del Proyecto

Configura las dependencias del proyecto agregando la librería en tus archivos de Gradle y el catálogo de versiones.

libs.versions.toml

[versions]
dicioVideo = "2.2.0"

[libraries]
dicio-videorecordersdk = { group = "io.bitbucket.juarezsdco", name = "videorecordersdk", version.ref = "dicioVideo" }

build.gradle

dependencies {
    implementation(libs.dicio.videorecordersdk)
}

2. Uso Básico

El SDK se provee a través del Composable DicioVideoCamera. A continuación se muestra un ejemplo de cómo implementar la pantalla que invoca al SDK:

VideoSdkScreen.kt

package com.tuapp.yourapp

import ai.dicio.videorecordersdkjc.core.VideoRecorderCallback
import ai.dicio.videorecordersdkjc.ui.screens.camera.DicioVideoCamera
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier

@Composable
fun VideoSdkScreen(token: String?, urlBase: String) {
    // Implementación del Callback
    val sdkCallback = remember {
        object : VideoRecorderCallback {
            override fun onSuccess(videoFilePath: String) {
                println("Video guardado en la ruta: $videoFilePath")
                // Aquí puedes cerrar la pantalla o subir el archivo al servidor
            }

            override fun onFailure(errorMessage: String) {
                println("Fallo en la grabación de video: $errorMessage")
            }

            override fun onCancel(cancelMessage: String) {
                println("Proceso cancelado: $cancelMessage")
            }

            override fun onCameraInfo(message: String) {
                println("Info de la cámara: $message")
            }
        }
    }

    Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
        if (token != null) {
            DicioVideoCamera(
                token = token,
                callback = sdkCallback,
                applicationID = "tu.application.id", // Reemplaza con tu ID real
                urlBase = urlBase,
                videoDuration = 15 // Opcional (10 a 30 segundos)
            )
        } else {
            CircularProgressIndicator()
        }
    }
}

Parámetros de DicioVideoCamera

Parámetro	Tipo	Descripción	Requerido	Valor por defecto
token	String	Token de autenticación de DICIO válido para autorizar el uso del SDK.	Sí	Ninguno
callback	VideoRecorderCallback	Implementación para recibir el video resultante y los eventos del SDK.	Sí	Ninguno
applicationID	String	El ID de tu aplicación. Usado para validaciones y licencias.	Sí	Ninguno
urlBase	String	URL base del servidor para validar el token y obtener la licencia.	Sí	Ninguno
videoDuration	Int	Duración del video en segundos. Solo se permiten valores de 10 a 30.	No	10
styledScreen	VideoStyled	Objeto que permite personalizar los textos, colores primarios y de fondo.	No	VideoStyled()

Manejo de Resultados y Eventos

Debes implementar la interfaz VideoRecorderCallback para reaccionar a todo el flujo de la grabación de video.

VideoRecorderCallback

interface VideoRecorderCallback {
    // Invocado cuando la grabación termina y el usuario la confirma.
    fun onSuccess(videoFilePath: String)

    // Invocado ante fallos críticos (ej. permisos denegados, errores de cámara).
    fun onFailure(errorMessage: String)

    // Invocado cuando el usuario regresa o cancela explícitamente.
    fun onCancel(cancelMessage: String)

    // Emite actualizaciones sobre el estado de la cámara y la grabación.
    fun onCameraInfo(message: String)
}

Métodos detallados:

1. onSuccess:

   • Descripción: Evento de finalización exitosa. Retorna la ruta absoluta al archivo .mp4 almacenado temporalmente en la caché del dispositivo (el archivo se reemplaza con cada intento para ahorrar espacio).
   • Parámetro: videoFilePath (Ruta física del video).

2. onCameraInfo:

   • Descripción: Envía métricas y actualizaciones de hardware. El formato entregado es un JSON estructurado.
   • Códigos Comunes:

Código	Descripción
CAMERA_STARTED	La vista previa de la cámara se ha inicializado correctamente.
CAMERA_STOPPED	La vista previa se detuvo o liberó el uso del hardware.
RECORDING_STARTED	Inició la captura de video y audio.
ALREADY_RECORDING	Se presionó el botón de inicio pero ya había una grabación en curso.
STOP_RECORDING	Se solicitó detener el video antes de tiempo o cuando finalizó el tiempo.
NO_RECORDING	Se intentó detener una grabación pero ninguna estaba en curso.

3. onFailure:
   • Descripción: Activado ante un error de validación, error de permisos o fallos de conexión.
   • Códigos Comunes (Típicamente enviados como JSON {"Code": "...", "Message": "..."}):

Código	Descripción
VIDEO_DURATION_NOT_VALID	El parámetro videoDuration se inicializó fuera del rango permitido de 10 a 30 segundos.
ERROR_PERMISSION	Se rechazó el permiso obligatorio de la cámara (CAMERA).
WARNING_PERMISSION	Se rechazó el permiso de audio (RECORD_AUDIO). El video se grabará sin sonido.
CAMERA_BIND_ERROR	Ocurrió un error al inicializar el servicio nativo de CameraX.
RECORDING_ERROR	Problema al almacenar o finalizar el archivo de video.
ERROR_JSON_EXCEPTION	Error al procesar y construir las respuestas internas del SDK.

4. onCancel:
   • Descripción: El usuario interrumpió la grabación al cerrar la interfaz mediante el botón de Atrás.
   • Código de Cancelación: Típicamente envía "USER_CANCEL".

3. Personalización de la Interfaz (Opcional)

Si necesitas adaptar la interfaz para que coincida con la marca de tu aplicación, puedes hacer uso del objeto VideoStyled.

Esta clase agrupa los textos (strings) y recursos de color, permitiéndote dictar rápidamente los tonos de fondo, botones y subtítulos.

VideoStyled.kt

package ai.dicio.videorecordersdkjc.ui.models.settings

import ai.dicio.videorecordersdkjc.R
import androidx.compose.ui.graphics.Color

data class VideoStyled (
    val title: Int = R.string.dicio_dv_title,
    val subtitle: Int = R.string.dicio_dv_subtitle,
    val titleSuccess: Int = R.string.dicio_dv_titile_success,
    val titleColor: Color = Color(0xff000000), // Negro por defecto
    val subtitleColor: Color = Color(0xff313131), // Gris oscuro por defecto
    val backgroundColor: Color = Color(0xffffffff), // Fondo blanco por defecto
    val primaryColor: Color = Color(0xff006407), // Verde institucional
    val secondaryColor: Color = Color(0xff91ea97), // Verde secundario
)

Ejemplo de cómo inyectarlo en tu vista:

LivenessScreen.kt

val myStyle = VideoStyled(
    // Personalizamos a una vista de Modo Oscuro y botones azules
    backgroundColor = Color.Black,
    titleColor = Color.White,
    subtitleColor = Color.LightGray,
    primaryColor = Color(0xFF007BFF) // Azul
)

DicioVideoCamera(
    token = token,
    callback = sdkCallback,
    applicationID = "tu.application.id",
    urlBase = "https://tu.url.base",
    videoDuration = 10,
    styledScreen = myStyle // <--- Asignado aquí
)