Skip to content

Guía de integración de biometría - SDK Android

SDK Identia Flow - Android

Descripción

El SDK Identia Flow tiene como propósito capturar una selfie y ambos lados de un documento de identidad para verificar la identidad del usuario.

Cómo Integrar el SDK

Configuración del Gradle

Añade la dependencia y el repositorio maven en el archivo build.gradle de tu módulo:

dependencies {
    implementation 'identia:flow:0.0.6'
}

repositories {
    maven {
        url "https://repo.repsy.io/mvn/identia/identia"
    }
}

Importaciones necesarias

En tu actividad o fragmento donde desees utilizar el SDK, asegúrate de importar:

import pe.identia.flow.FlowActivity

Actualización del AndroidManifest.xml

Añade la actividad FlowActivity a tu AndroidManifest.xml:

<activity android:name="pe.identia.flow.FlowActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="pe.identia.camera.OPEN_FLOW" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Obtención del Token de Acceso desde el Backend

Es esencial que la obtención del token de acceso se realice en el backend de tu aplicación para no exponer las credenciales. Una vez que tu backend haya obtenido el token, puede enviarlo al frontend (tu aplicación Android) de manera segura para que pueda ser utilizado en solicitudes subsiguientes al servidor.

Uso del SDK

Una vez que hayas recibido el token de acceso desde tu backend se deberá crear un proceso biométrico. El Id resultante se deberá asignar al valor "YOUR_OBTAINED_ID" en tu aplicación Android.

Crea un Intent para FlowActivity y pasa los datos necesarios como extras:

Parámetros requeridos: - idSession (String): ID del proceso biométrico obtenido desde el backend - endPoint (String): URL base del servidor (ej: "https://apifacialdev.identia.pe/")

Parámetros opcionales: - style (String): ID de personalización gráfica obtenido desde Backoffice

val intent = Intent(this@MainActivity, FlowActivity::class.java)
intent.putExtra("idSession", YOUR_OBTAINED_ID)
intent.putExtra("endPoint", "https://apifacialdev.identia.pe/")

if (intent.resolveActivity(packageManager) != null) {
    startActivity(intent)
} else {
    // Maneja el caso en el que no se encuentra la actividad
}

Personalización gráfica

Si has creado una personalización de la interfaz en tu Backoffice, puedes agregarla a tu FlowActivity mediante el parámetro style. El PERSONALIZATION_ID se obtiene directamente del Backoffice. Para hacerlo, agrega el ID de tu personalización como valor de este parámetro en el Intent que inicia la actividad, como se muestra en el siguiente ejemplo:

val intent = Intent(this@MainActivity, FlowActivity::class.java)
intent.putExtra("idSession", YOUR_OBTAINED_ID)  // Corregido a "idSession" para claridad.
intent.putExtra("endPoint", "https://apifacialdev.identia.pe/")
intent.putExtra("style", PERSONALIZATION_ID)

if (intent.resolveActivity(packageManager) != null) {
    startActivity(intent)
} else {
    // Maneja el caso en el que no se encuentra la actividad
}

Respuestas del SDK

El SDK entrega un único string JSON en el extra "response" del Intent de resultado. Según el caso, ese JSON corresponde al flujo biométrico (UI web, campo msg) o a un error nativo del SDK (validación de entrada o permisos, campo message). Esta guía documenta ambos formatos.

Cómo recibe la respuesta

Utilice ActivityResultLauncher con FlowActivity. Cuando el SDK cierra la actividad con resultado, lea:

val raw = result.data?.getStringExtra("response")
Origen Cuándo ocurre Campo de motivo
Flujo biométrico (UI web) El usuario interactuó con la UI y el proceso terminó msg
Error nativo del SDK idSession o endPoint inválidos, o permiso de cámara no concedido message

El SDK no modifica el JSON que envía la UI web: lo reenvía tal cual. Los errores nativos los construye el SDK con message, code y data: null (sin msg).

Dos formatos de respuesta

Respuesta del flujo biométrico Error nativo del SDK
Cuándo Tras usar la UI de verificación Antes o sin completar el flujo (validación o permisos)
Motivo Campo msg Campo message (texto en español)
data Puede incluir process_data u omitirse Siempre null
result true o false Siempre false

En la práctica, si el JSON incluye msg, corresponde al flujo biométrico documentado en los anexos. Si incluye message con uno de los code y textos de la tabla siguiente (y no incluye msg), corresponde a un error nativo del SDK.

Ejemplo mínimo de recepción:

resultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    val raw = result.data?.getStringExtra("response") ?: return@registerForActivityResult
    val json = JSONObject(raw)
    // Flujo biométrico: json.optString("msg")
    // Error nativo del SDK: json.optString("message") y json.optInt("code")
}

Errores nativos del SDK

El SDK genera solo estos JSON antes o sin completar el flujo web. Siempre incluyen result: false, data: null y no incluyen msg.

code message Cuándo
401 Por favor, otorga permisos de cámara para continuar. El usuario no concedió permiso de cámara
501 Endpoint incorrecto. Se esperaba 'identia.pe'. endPoint no es un dominio identia.pe válido
502 Para continuar, es necesario que envíe un idSession válido. idSession no cumple el formato esperado

Permiso de cámara denegado (401):

{
  "result": false,
  "message": "Por favor, otorga permisos de cámara para continuar.",
  "code": 401,
  "data": null
}

idSession inválido (502):

{
  "result": false,
  "message": "Para continuar, es necesario que envíe un idSession válido.",
  "code": 502,
  "data": null
}

endPoint inválido (501):

{
  "result": false,
  "message": "Endpoint incorrecto. Se esperaba 'identia.pe'.",
  "code": 501,
  "data": null
}

En estos casos el SDK también devuelve Activity.RESULT_OK con el extra "response" (igual que en el flujo web).

Flujo biométrico (respuesta con msg)

Cuando el usuario completa o interrumpe la UI biométrica, el SDK reenvía un JSON con msg (y, según el caso, id, confidence, process_data, etc.) sin alterarlo. El motivo del rechazo o del error de captura es el valor de msg, no un texto genérico en message.

Referencias:

Ejemplo de rechazo biométrico (reenviado sin modificar desde la UI web):

{
  "result": false,
  "msg": "liveness:selfie",
  "code": 200,
  "id": "abc123...",
  "confidence": 0.12
}

En las respuestas del flujo biométrico, result: false con code: 200 puede indicar un challenge no superado; el code describe el estado del resultado, no necesariamente un HTTP 200.

Cierre sin JSON en "response"

En algunos cierres de FlowActivity el integrador puede recibir resultCode != Activity.RESULT_OK o un extra "response" nulo o vacío (por ejemplo, si el usuario abandona la pantalla o la navegación sale de la URL del proceso). En esos casos el SDK no entrega un JSON de resultado biométrico ni un error nativo de la tabla anterior.

Errores frecuentes y soluciones

1. Problemas de Sincronización del Gradle

Error: Cambios en el build.gradle no se reflejan, o la dependencia del SDK no se resuelve correctamente.

Solución:

  1. Ejecuta "Clean Project" y luego "Rebuild Project" en Android Studio.
  2. Verifica que tu conexión a Internet esté activa y funcione correctamente.
  3. Asegúrate de que la URL del repositorio Maven esté escrita correctamente en el build.gradle.

2. Errores de Importación

Error: La clase FlowActivity no se encuentra o no se puede importar.

Solución:

  1. Confirma que la dependencia del SDK se ha añadido correctamente en el build.gradle.
  2. Realiza una sincronización del Gradle y reconstruye el proyecto.

3. Problemas de Ejecución de FlowActivity

Error: La aplicación se cierra o no inicia FlowActivity al intentar ejecutar el Intent.

Solución:

  1. Verifica que FlowActivity esté declarada correctamente en el AndroidManifest.xml.
  2. Asegúrate de que todos los datos necesarios se pasan correctamente al Intent.

4. Errores de Permiso de Cámara

Error: La aplicación no solicita permiso para usar la cámara, o el SDK devuelve JSON con code: 401 y message: "Por favor, otorga permisos de cámara para continuar." (véase Errores nativos del SDK).

Solución:

  1. Confirma que los permisos de cámara están declarados en el AndroidManifest.xml.
  2. Implementa una comprobación de permisos en tiempo de ejecución antes de iniciar FlowActivity, o contempla la respuesta nativa 401 descrita en Errores nativos del SDK.

5. Problemas de Conectividad con el Backend

Error: No se recibe el token de acceso desde el backend.

Solución:

  1. Verifica la conectividad de red de la aplicación.
  2. Asegúrate de que el endpoint del backend esté operativo y accesible.
  3. Revisa la implementación del servicio que obtiene el token para identificar posibles errores.

6. Problemas de Respuesta del SDK

Error: Respuestas inesperadas, nulas, o JSON con message en lugar de msg.

Solución:

  1. Comprueba si el JSON trae msg (flujo biométrico) o message con los códigos nativos documentados en Errores nativos del SDK.
  2. Si no hay extra "response", revisa Cierre sin JSON en "response".
  3. Verifica que idSession y endPoint cumplen el formato esperado antes de abrir FlowActivity.

7. Problemas de Rendimiento o Inestabilidad

Error: La aplicación se vuelve lenta o inestable después de integrar el SDK.

Solución:

  1. Revisa el uso de memoria y CPU de tu aplicación para identificar posibles fugas de memoria o bucles infinitos.
  2. Actualiza a la última versión del SDK, ya que puede incluir optimizaciones y correcciones de errores.

8. Errores de Compilación Después de Actualizaciones

Error: Errores de compilación después de actualizar el SDK.

Solución:

  1. Limpia el proyecto (Clean Project) y reconstrúyelo (Rebuild Project).
  2. Revisa las notas de la versión del SDK para cualquier cambio en la API o en las dependencias.

Incluir esta sección en la documentación o FAQ de tu SDK ayudará a los desarrolladores a resolver rápidamente problemas comunes, mejorando la experiencia general de integración del SDK Identia Flow.