BlackBox (Caja Negra) - ReconoSERID/SDK-ReconoSERID-Android GitHub Wiki

Documentación de `BlackBoxActivity`

Descripción

BlackBoxActivity es una actividad diseñada para ejecutar el flujo biométrico completo dentro de un entorno controlado (BlackBox). Todas las pantallas son administradas internamente por el SDK, permitiendo ejecutar el proceso de validación de forma segura, consistente y con alto rendimiento.

La aplicación cliente únicamente debe configurar el proceso, iniciar la actividad y recibir el resultado final. Todo el flujo de captura documental, captura biométrica y validación es administrado por el SDK.

Características Clave

Flujo cerrado: Todas las pantallas son administradas por BlackBoxActivity.
Vistas pre-renderizadas: Reduce tiempos de carga y mejora la experiencia del usuario.
Configuración centralizada: El proceso documental y biométrico se configura antes de iniciar el flujo.
Alto rendimiento: Optimizado para procesos biométricos.
Entorno seguro: Evita interferencias externas durante la ejecución.
Respuesta unificada: El resultado del proceso se recibe mediante la Activity Result API.

Dependencias requeridas

import androidx.activity.result.contract.ActivityResultContracts

import com.reconosersdk.reconosersdk.common.UiCustomization
import com.reconosersdk.reconosersdk.http.olimpiait.entities.`in`.BiometricConfigurationModel
import com.reconosersdk.reconosersdk.http.olimpiait.entities.`in`.BlackBoxDataIn
import com.reconosersdk.reconosersdk.http.olimpiait.entities.`in`.BlackBoxDataTransport
import com.reconosersdk.reconosersdk.http.olimpiait.entities.`in`.DocumentConfigurationModel
import com.reconosersdk.reconosersdk.ui.form.view.BlackBoxActivity
import com.reconosersdk.reconosersdk.utils.BiometricConfigurationTransport
import com.reconosersdk.reconosersdk.utils.DocumentConfigurationTransport
import com.reconosersdk.reconosersdk.utils.IntentExtras

Flujo de integración

Aplicación Cliente
        │
        ▼
Crear BlackBoxDataIn
        │
        ▼
Configurar Documento
        │
        ▼
Configurar Biometría
        │
        ▼
Crear Intent
        │
        ▼
BlackBoxActivity
        │
        ▼
Resultado
 ├── RESULT_OK
 ├── ERROR_INTENT
 └── RESULT_CANCELED

Inicialización

private fun startBlackBox() {

    val blackBoxData = BlackBoxDataIn(
        adviser = "SDK OlimpiaIT",
        ciudadanoData = "SDK OlimpiaIT",
        validationType = 4,
        documentType = documentType,
        documentNumber = documentNumber,
        email = null,
        cellPhone = "310888888",
        prefCellPhone = "57",
        user = "usuario",
        password = "password",
        guidConv = "GUID_CONVENIO",
        consultaFuentes = true,
        infCandidato = "{\"company\":\"OlimpiaIt\"}",
        procesoWhatsapp = false,
        processType = 0,
        branch = "SDK OlimpiaIT"
    )

    val uiCustomization = UiCustomization()

    val documentConfiguration = DocumentConfigurationModel(
        tutorialEnabled = true,
        previewEnabled = true,
        resultEnabled = true,
        attempts = 3,
        processTime = 15,
        initialTime = 5,
        soundEnabled = false,
        uiCustomization = uiCustomization,
        accessibilityEnabled = false
    )

    val biometricConfiguration = BiometricConfigurationModel(
        tutorialEnabled = true,
        previewEnabled = true,
        resultEnabled = true,
        soundEnabled = false,
        accessibilityEnabled = false,
        processTime = 15,
        attempts = 3,
        uiCustomization = uiCustomization
    )

    val intent = Intent(this, BlackBoxActivity::class.java).apply {

        BlackBoxDataTransport.put(blackBoxData)

        DocumentConfigurationTransport.put(
            this,
            documentConfiguration
        )

        BiometricConfigurationTransport.put(
            this,
            biometricConfiguration
        )

        putExtra(IntentExtras.SAVE_DOCUMENT, false)
    }

    blackBoxLauncher.launch(intent)
}

Configuración del proceso

Información del proceso (`BlackBoxDataIn`)

Parámetro	Tipo	Descripción
`adviser`	`String`	Nombre del asesor que inicia el proceso.
`ciudadanoData`	`String`	Información adicional del ciudadano.
`validationType`	`Int`	Tipo de validación.
`documentType`	`String`	Tipo de documento (`CC`, `TI`, `CE`, etc.).
`documentNumber`	`String`	Número del documento.
`email`	`String?`	Correo electrónico.
`cellPhone`	`String`	Celular del ciudadano.
`prefCellPhone`	`String`	Prefijo internacional.
`user`	`String`	Usuario del convenio.
`password`	`String`	Contraseña del convenio.
`guidConv`	`String`	GUID del convenio.
`consultaFuentes`	`Boolean`	Consulta fuentes externas.
`infCandidato`	`String`	Información adicional en formato JSON.
`procesoWhatsapp`	`Boolean`	Flujo WhatsApp.
`processType`	`Int`	Tipo de proceso.
`branch`	`String`	Sede del proceso.

Configuración documental (`DocumentConfigurationModel`)

Parámetro	Tipo	Default	Descripción
`tutorialEnabled`	Boolean	Variable	Muestra el tutorial documental.
`previewEnabled`	Boolean	Variable	Habilita la vista previa del documento.
`resultEnabled`	Boolean	Variable	Muestra la pantalla de resultado documental.
`attempts`	Int	Variable	Número máximo de intentos.
`processTime`	Int	Variable	Tiempo máximo del proceso.
`initialTime`	Int	Variable	Tiempo inicial antes de comenzar la captura.
`soundEnabled`	Boolean	`true`	Habilita sonidos del flujo documental.
`accessibilityEnabled`	Boolean	`false`	Activa funciones de accesibilidad.
`uiCustomization`	`UiCustomization`	Variable	Personalización visual del flujo.

Configuración biométrica (`BiometricConfigurationModel`)

Parámetro	Tipo	Default	Descripción
`tutorialEnabled`	Boolean	Variable	Muestra el tutorial biométrico.
`previewEnabled`	Boolean	Variable	Habilita la vista previa biométrica.
`resultEnabled`	Boolean	Variable	Muestra el resultado de la captura.
`attempts`	Int	Variable	Número máximo de intentos biométricos.
`processTime`	Int	Variable	Tiempo máximo de captura.
`soundEnabled`	Boolean	`true`	Habilita sonidos durante el proceso.
`accessibilityEnabled`	Boolean	`false`	Activa funciones de accesibilidad.
`uiCustomization`	`UiCustomization`	Variable	Personalización visual.
`instantFeedbackConfiguration`	`InstantFeedbackConfig?`	`null`	⚠️ Deprecated. Este parámetro ya no es utilizado por el flujo BlackBox. El SDK ignora cualquier valor enviado. Se mantiene únicamente por compatibilidad con versiones anteriores y no debe utilizarse en nuevas implementaciones.

Parámetros adicionales del Intent

Parámetro	Tipo	Default	Descripción
`IntentExtras.SAVE_DOCUMENT`	Boolean	`false`	Controla el comportamiento de almacenamiento documental del SDK.

Inicio del flujo

Se recomienda utilizar la Activity Result API.

private val blackBoxLauncher =
    registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->

        when(result.resultCode){

            RESULT_OK -> {
                //Proceso exitoso
            }

            IntentExtras.ERROR_INTENT -> {
                //Proceso con error
            }

            RESULT_CANCELED -> {
                //Usuario canceló el proceso
            }

        }

    }

Respuesta satisfactoria

Cuando el proceso finaliza correctamente:

RESULT_OK
IntentExtras.SUCCESS_PROCESS = true

Ejemplo:

RESULT_OK -> {

    val success =
        result.data?.getBooleanExtra(
            IntentExtras.SUCCESS_PROCESS,
            false
        ) == true

    if(success){

        val validationData =
            result.data?.getStringExtra("validation_data")

        val codigoCliente =
            result.data?.getStringExtra("codigoCliente")

        val primerNombre =
            result.data?.getStringExtra("primerNombre")

    }

}

Respuesta de error

Cuando ocurre un error durante el flujo:

IntentExtras.ERROR_INTENT

Información disponible:

Extra	Descripción
`IntentExtras.ERROR_MSG`	Mensaje principal del error.
`IntentExtras.CONSULT_VALIDATION_DATA_JSON`	Información parcial de la validación.
`IntentExtras.CONSULT_VALIDATION_ERROR_JSON`	Error generado durante ConsultValidation.
`IntentExtras.REQUEST_VALIDATION_ERROR_JSON`	Error generado durante RequestValidation.
`validation_data`	Información de validación cuando se encuentre disponible.