Captura de documentos

Descripción General

Esta documentación proporciona una guía detallada para desarrolladores sobre cómo integrar e implementar el componente Composable DicioCameraDocument en sus aplicaciones Android con Jetpack Compose. El SDK ha sido rediseñado para ofrecer una integración nativa en Compose, permitiendo la captura de imágenes de documentos de manera eficiente y segura.

Requisitos Previos

Compatibilidad

Lenguaje	Versión Android	Versión SDK	Android Studio
Kotlin/Java	Android 7+	24+	Jellyfish+

Permisos en el Manifest: Asegúrate de agregar los siguientes permisos en tu archivo AndroidManifest.xml:

AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />

Configuración del Proyecto: Añade las siguientes dependencias en tu archivo build.gradle:

build.gradle
// Dependencia del SDK de Dicio
implementation(files("libs/documentcapturesdk.aar"))

// Dependencias de CameraX requeridas por el SDK
implementation(libs.androidx.camerax.core)
implementation(libs.androidx.camerax.camera2)
implementation(libs.androidx.camerax.lifecycle)
implementation(libs.androidx.camerax.view)

implementation(libs.androidx.lifecycle.viewmodel.compose)
// El SDK utiliza internamente un ViewModel, es recomendable tener esta dependencia
implementation(libs.androidx.lifecycle.viewmodel.compose)
    
// Dependencia para realizar las llamadas de red para la licencia
implementation(libs.okhttp3)

Configuración del Proyecto: Añade las siguientes dependencias en tu archivo libs.versions.toml:

libs.versions.toml
[versions]
camerax = "1.3.0" # O una versión más reciente y estable
lifecycle = "2.8.1"
okhttp = "4.12.0"

[libraries]
androidx-camerax-core = { group = "androidx.camera", name = "camera-core", version.ref = "camerax" }
androidx-camerax-camera2 = { group = "androidx.camera", name = "camera-camera2", version.ref = "camerax" }
androidx-camerax-lifecycle = { group = "androidx.camera", name = "camera-lifecycle", version.ref = "camerax" }
androidx-camerax-view = { group = "androidx.camera", name = "camera-view", version.ref = "camerax" }
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
okhttp3 = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }

Integración y Uso

El SDK se integra como un componente @Composable. Simplemente llama a la función DicioCameraDocument dentro de tu jerarquía de Compose. El componente manejará internamente la carga y validación de la licencia antes de mostrar la cámara.

Parámetros del Composable

Composable.kt
@Composable
fun DicioCameraDocument(
    styledScreen: dicioDocumentStyled = dicioDocumentStyled(),
    callback: DicioCaptureCallback,
    applicationID: String,
    token: String,
    urlBase: String
)

styledScreen:(opcional): Un objeto dicioDocumentStyled para personalizar la apariencia de la pantalla.
callback: Implementación de DicioCaptureCallback para manejar los eventos del SDK.
applicationID: (Requerido) El ID de la aplicación proporcionado para la validación de la licencia.
token: (Requerido) El token de autenticación (Bearer Token) para autorizar las solicitudes.
urlBase:(Requerido) La URL base del servidor donde se validará el token y la licencia.

Personalización (Programática)

La personalización de la interfaz se realiza proveyendo un objeto de configuración dicioDocumentStyled al componente. Clase dicioDocumentStyled

Propiedad	Tipo	Descripción	Valor por Defecto
`title`	`Int` (StringRes)	ID del recurso de texto para el título.	`R.string.dicio_dc_title`
`subtitle`	`Int` (StringRes)	ID del recurso de texto para el subtítulo.	`R.string.dicio_dc_subtitle`
`backgroundColor`	`Color`	Color de fondo de la pantalla de captura.	`Color(0xFF000000)` (Negro)
`titleColor`	`Color`	Color del texto del título.	`Color.White`
`subtitleColor`	`Color`	Color del texto del subtítulo.	`Color.White`
`buttonCaptureColor`	`Color`	Color del botón de captura.	`Color.White`
`buttonCancelColor`	`Color`	Color del icono para cerrar/cancelar.	`Color.White`

Implementación de Callbacks

Debes implementar la interfaz DicioCaptureCallback para recibir las respuestas y eventos del SDK.

Método	Descripción	Parámetros
`DicioCaptureOnSuccess`	Se invoca cuando la captura de imagen es exitosa.	`image`: Imagen capturada en formato `String` (Base64).
`DicioCaptureOnFailure`	Se invoca cuando hay un error durante el proceso.	`errorMessage`: Mensaje de error en formato `String` (JSON).
`DicioCaptureOnCancel`	Se invoca cuando el usuario cancela la captura.	`cancelMessage`: Mensaje explicando por qué se canceló.
`DicioCaptureOnInfoCamera`	Proporciona información sobre el estado de la cámara.	`message`: Mensaje de información en formato `String` (JSON).

Ejemplo de Uso Completo

El siguiente ejemplo muestra cómo integrar DicioCameraDocument, pasar los parámetros de validación y manejar el resultado.

Ejemplo de Uso

@Composable
fun DocumentCaptureScreen(
    // Estos valores deben venir de tu lógica de negocio
    appId: String,
    userToken: String,
    apiBaseUrl: String
) {
    var capturedImageBase64 by remember { mutableStateOf<String?>(null) }

    if (capturedImageBase64 == null) {
        // Muestra el componente del SDK
        DicioCameraDocument(
            // Pasa los parámetros requeridos para la validación
            applicationID = appId,
            token = userToken,
            urlBase = apiBaseUrl,
            
            // Implementa el callback para recibir los resultados
            callback = object : DicioCaptureCallback {
                override fun DicioCaptureOnSuccess(image: String) {
                    capturedImageBase64 = image
                    println("Imagen capturada con éxito.")
                }

                override fun DicioCaptureOnFailure(errorMessage: String) {
                    // El SDK ya muestra errores de licencia, pero aquí
                    // puedes manejar otros errores o registrarlos.
                    println("Error en captura: $errorMessage")
                }

                override fun DicioCaptureOnCancel(cancelMessage: String) {
                    println("Captura cancelada: $cancelMessage")
                    // Aquí puedes navegar hacia atrás
                }

                override fun DicioCaptureOnInfoCamera(message: String) {
                    println("Info Cámara: $message")
                }
            }
        )
    } else {
        // Muestra la foto capturada con un botón para volver
        CapturedPhotoResult(
            base64Image = capturedImageBase64,
            onRetake = {
                capturedImageBase64 = null // Vuelve a la cámara
            }
        )
    }
}

Manejo de Errores y Códigos de Respuesta

Los mensajes se entregan como una cadena con formato JSON con las claves "Code" y "Message".

Errores de Licencia y Conectividad Estos errores ocurren antes de que la cámara se muestre. El SDK mostrará un mensaje en pantalla y también lo notificará vía DicioCaptureOnFailure.

Código de error	Descripción
`NO_INTERNET`	No hay conexión a internet disponible para validar la licencia.
`APPLICATION_ID_EMPTY`	El parámetro applicationID está vacío.
`BASE_URL_EMPTY`	El parámetro urlBase está vacío.
`TOKEN_EMPTY`	El parámetro token está vacío.
`TOKEN_NOT_VALID`	El token proporcionado no es válido o ha expirado.
`SERVER_ERROR_NOT_LICENCE`	La respuesta del servidor no contenía una clave de licencia.
`JSON_PARSE_ERROR`	Error al procesar la respuesta del servidor.
`SERVER_ERROR`	Error general de comunicación con el servidor de licencias.

Errores de Cámara

Código de error	Descripción
`ERROR_PERMISSION`	Permiso de cámara denegado por el usuario.
`ERROR_CAMERA`	Error general al iniciar o vincular la cámara.
`ERROR_TAKING_PHOTO`	Error durante la captura de la foto (devuelto por CameraX).
`ERROR_IMAGE_FORMAT`	El formato de la imagen de la cámara no es JPEG.

Mensajes de Información de Cámara

Código de información	Descripción
`CAMERA_STARTED`	La cámara se inició correctamente y está lista para capturar.
`CAMERA_TAKE_PHOTO`	La foto ha sido tomada y está siendo procesada. Exportar a Hojas de cálculo

Descripción General​

Requisitos Previos​

Compatibilidad​

Integración y Uso​

Personalización (Programática)​

Implementación de Callbacks​

Ejemplo de Uso Completo​

Ejemplo de Uso​

Manejo de Errores y Códigos de Respuesta​