MÓDULO NATIVO

OCR

Esta documentación provee una guía detallada para desarrolladores sobre cómo integrar e implementar el componente SDK OCR en aplicaciones Android utilizando Jetpack Compose. El SDK permite la captura y procesamiento eficiente y seguro de datos de documentos de identificación.

Regresar

ANDROIDJETPACK COMPOSEv2.2.0

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.

[versions]
dicioOcr = "2.2.0"

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

dependencies {
    implementation(libs.dicio.ocrsdk)
}

2. Uso Básico

El SDK se proporciona como un Composable de Jetpack Compose llamado DicioCamera. Debes invocar este Composable en el punto de tu UI donde desees mostrar la interfaz de escaneo.

package com.tuapp.yourapp

import ai.dicio.ocrsdk.core.OcrCallback
import ai.dicio.ocrsdk.ui.models.settings.OcrResult
import ai.dicio.ocrsdk.ui.screens.camera.DicioCamera
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import kotlin.time.Duration.Companion.seconds
import android.util.Log
import org.json.JSONException
import org.json.JSONObject

// ... (Tu lógica para obtener el token)
// Por ejemplo, usando State para manejar el token
sealed class TokenState {
    object Loading : TokenState()
    data class Success(val token: String) : TokenState()
    data class Error(val message: String) : TokenState()
}

@Composable
fun OcrScreen(tokenState: TokenState, modifier: Modifier = Modifier) {
    // ... (Mostrar pantalla de carga, error o SDK dependiendo del tokenState) ...

    when(tokenState) {
        TokenState.Loading -> { /* Mostrar indicador de carga */ }
        is TokenState.Error -> { /* Mostrar mensaje de error */ }
        is TokenState.Success -> {
            // Cuando el token esté listo, mostrar la DicioCamera
            DicioCameraIntegration(token = tokenState.token, modifier = modifier)
        }
    }
}

@Composable
fun DicioCameraIntegration(token: String, modifier: Modifier = Modifier) {
    // Debes proveer tu applicationId y la URL base de tu API
    val myApplicationId = "tu.application.id" // Reemplaza con tu Application ID real
    val myUrlBase = "https://tu_url" // Reemplaza con tu URL base real

    val ocrCallback = remember {
        object : OcrCallback {
            override fun onSuccess(result: OcrResult) {
                // Escaneo exitoso. Procesa los datos recibidos.
                Log.d("OCR_SDK", "¡Escaneo exitoso!")
                Log.d("OCR_SDK", "Result Data: \${result.resultData}") // Datos extraídos en formato JSON
                Log.d("OCR_SDK", "Face Image B64 (primeros 50 chars): \${result.faceImageBase64.take(50)}...")
                Log.d("OCR_SDK", "Front Image B64 (primeros 50 chars): \${result.frontImageBase64.take(50)}...")
                Log.d("OCR_SDK", "Back Image B64 (primeros 50 chars): \${result.backImageBase64.take(50)}...")

                // Aquí puedes navegar para cerrar la pantalla del SDK y procesar los datos
            }

            override fun onGuidanceMessage(message: String) {
                // Mensajes de guía durante el escaneo
                Log.d("OCR_SDK", "Mensaje de guía: $message")
                // Puedes parsear el "message" para obtener el código
                val code = getCodeFromJsonString(message)
                when (code) {
                    "UX_REQUEST_SIDE_BACK" -> Log.d("OCR_SDK", " -> Se requiere escanear la parte trasera.")
                    "UX_REQUEST_SIDE_FRONT" -> Log.d("OCR_SDK", " -> Se requiere escanear la parte frontal.")
                    // Manejar otros códigos si es necesario
                }
            }

            override fun onFailure(error: String) {
                // Ocurrió un error que impidió completar el escaneo
                Log.e("OCR_SDK", "Error de escaneo: $error")
                // Cerrar o salir de la pantalla del SDK y notificar al usuario
            }

            override fun onCancel(message: String) {
                // El escaneo fue cancelado (por el usuario o por límite de tiempo)
                Log.w("OCR_SDK", "Escaneo cancelado: $message")
                // Cerrar o salir de la pantalla del SDK y notificar al usuario
            }
        }
    }

    // Invocar el Composable DicioCamera
    DicioCamera(
        callback = ocrCallback,
        applicationID = myApplicationId,
        token = token, // El token obtenido previamente
        urlBase = myUrlBase, // La URL base de tu API
        seconds = 60, // Tiempo máximo para el escaneo
    )
}

// Función de ayuda para extraer el código del mensaje JSON
fun getCodeFromJsonString(jsonString: String): String? {
    return try {
        val jsonObject = JSONObject(jsonString)
        if (jsonObject.has("Code")) {
            jsonObject.getString("Code")
        } else {
            null
        }
    } catch (e: JSONException) {
        e.printStackTrace()
        null
    }
}

Parámetros de DicioCamera

Parámetro	Tipo	Descripción	Requerido	Valor por Defecto
`callback`	`OcrCallback`	Implementación de la interfaz `OcrCallback` para recibir resultados, mensajes de guía, errores y cancelaciones del SDK.	Sí	Ninguno
`applicationID`	`String`	Tu ID de aplicación. Usado internamente por el SDK para la gestión de licencia.	Sí	Ninguno
`token`	`String`	Token de autenticación. Usado por el SDK para validar la sesión y obtener la licencia desde tu API. Debe ser un token válido.	Sí	Ninguno
`urlBase`	`String`	La URL base de tu API donde el SDK validará el token y obtendrá la configuración de la licencia.	Sí	Ninguno
`seconds`	`Int`	Duración máxima permitida para el proceso de escaneo. Si se excede, el SDK se cancelará automáticamente con el código `TIMEOUT_CANCEL`.	No	`50`
`styledScreen`	`OcrStyled`	Objeto que permite personalizar la apariencia de la interfaz del SDK (colores, textos, logo).	No	`OcrStyled()`

3. Manejo de Resultados y Eventos

Debes implementar la interfaz OcrCallback para recibir las respuestas del SDK.

data class OcrResult(
    val resultData: String,
    val faceImageBase64: String,
    val frontImageBase64: String,
    val backImageBase64: String
)

interface OcrCallback {
    // Llamado cuando el escaneo se completa exitosamente y los datos son extraídos
    fun onSuccess(result: OcrResult)

    // Llamado para proveer mensajes de guía al usuario durante el escaneo
    fun onGuidanceMessage(message: String) // Mensaje JSON con código y descripción

    // Llamado cuando ocurre un error que impide completar el escaneo
    fun onFailure(error: String) // Mensaje descriptivo de error

    // Llamado cuando el proceso de escaneo es cancelado
    fun onCancel(message: String) // Mensaje descriptivo de cancelación (ej. usuario, timeout)
}

Métodos a implementar

1. onSuccess:

Descripción: Invocado cuando la verificación OCR es exitosa.
Parámetros:
- result: Objeto OcrResult que contiene el resultData (JSON) y las imágenes extraídas (faceImageBase64, frontImageBase64, backImageBase64).

2. onGuidanceMessage:

Descripción: Invocado durante el proceso de escaneo.
Parámetros:
- message: Eventos UX en formato JSON.
Tabla de Códigos:

Código	Descripción
`UX_REQUEST_SIDE_FRONT`	Se solicita al usuario escanear la parte frontal del documento.
`UX_REQUEST_SIDE_BACK`	Se solicita al usuario escanear la parte trasera del documento.
`DOCUMENT_NOT_FOUND`	El documento no fue detectado en la cámara.
`UX_DOCUMENT_NOT_FULLY_VISIBLE`	El documento no es completamente visible.
`UX_DOCUMENT_LOCATED`	El documento ha sido detectado y localizado con éxito.
`UX_DOCUMENT_TOO_FAR`	El documento está muy lejos de la cámara.
`UX_DOCUMENT_TOO_CLOSE`	El documento está muy cerca de la cámara.
`UX_TOO_CLOSE_TO_EDGE`	El documento está muy cerca del borde de la cámara.
`UX_DOCUMENT_TOO_TILTED`	El documento está muy inclinado.
`UX_BLUR_DETECTED`	Se ha detectado desenfoque. La imagen no es nítida.
`UX_GLARE_DETECTED`	Se ha detectado brillo o reflejo. Evita la luz directa.
`UX_WRONG_SIDE`	Se está intentando escanear el lado equivocado del documento.
`UX_SCANNING_DONE`	El proceso de escaneo UX (captura visual) ha terminado.
`UX_UNKNOWN_EVENT`	Se recibió un evento desconocido de la interfaz de usuario.

3. onFailure:

Descripción: Invocado cuando hay un error durante el proceso.
Parámetro:
- error: Mensaje descriptivo del error en formato JSON.
Tabla de Códigos:

Código	Descripción
`DOCUMEN_NOT_VALID`	El documento escaneado no es válido.
`ERROR_PERMISSION`	Permisos de cámara denegados.
`ERROR_SDK`	Error interno del SDK o licencia inválida.
`UNRECOVERABLE_ERROR`	Ocurrió un error crítico no recuperable.
`TOKEN_EMPTY`	El token está vacío o falta.
`NO_INTERNET`	Sin conexión a internet.
`LICENCE_OR_TOKEN_ERROR`	Licencia o token inválido.
`TOKEN_NOT_VALID`	Token inválido.

4. onCancel:

Descripción: Invocado cuando el usuario cancela la verificación.
Parámetro:
- message: Mensaje explicando por qué se canceló el proceso.
Tabla de Códigos:

Código de Cancelación	Descripción
`TIMEOUT_CANCEL`	La sesión se canceló por exceder el tiempo de espera (1 minuto).
`USER_CANCEL`	El usuario canceló el proceso.

4. Personalización de la Interfaz (Opcional)

Si deseas personalizar la apariencia de la pantalla de escaneo (textos, colores, logo), puedes hacerlo proveyendo un objeto OcrStyled al parámetro styledScreen.

El objeto OcrStyled es un data class con los siguientes campos:

val styledSdk = OcrStyled(
    modalTitle = R.string.ocr_modal_title_instructions,
    modalContent = R.string.ocr_modal_subtitle_instructions,

    timeoutModalTitle = R.string.ocr_modal_timeout_title_instructions,
    timeoutModalContent = R.string.ocr_modal_timeout_subtitle_instructions,

    logo = R.drawable.logo,

    titleColor = Color.Black,
    contentColor = Color.Gray,
    iconColor = Color.White,
    scannerColor = Color.White,

    timeoutModalButtonText = R.string.button_cancel,

    backgroundColor = Color.White
)

Ejemplo de uso:

DicioCamera(
    callback = sdkCallback,
    applicationID = viewModel.aplicationId,
    token = token,
    urlBase = viewModel.urlBase,
    seconds = viewModel.timeOut,
    styledScreen = styledSdk
)

OCR

Compatibilidad y Requisitos

1. Configuración del Proyecto

libs.versions.toml

build.gradle

2. Uso Básico

OcrScreen.kt

Parámetros de DicioCamera

3. Manejo de Resultados y Eventos

OcrCallback.kt

Métodos a implementar

4. Personalización de la Interfaz (Opcional)

OcrStyled.kt

Ejemplo de uso:

Usage.kt