Skip to content

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

SDK Identia Flow - iOS

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. Está diseñado con SwiftUI.

Cómo Integrar el SDK

Descarga del SDK

  • El SDK estará disponible como un archivo .zip. Deberás descargar y descomprimir este archivo para obtener el .framework.
  • Ofrecemos dos variantes del SDK Identia Flow, una con Bitcode habilitado y otra sin Bitcode. Elige la opción que mejor se ajuste a las necesidades de tu proyecto.

Configuración del SDK

Con Bitcode Habilitado:

Este paquete incluye Bitcode, lo cual es recomendable si deseas que Apple recompile tu aplicación para futuros dispositivos sin necesidad de subir una nueva versión.

Sin Bitcode:

Elige esta opción si prefieres una compilación más rápida de tu aplicación durante el desarrollo o si no necesitas la compatibilidad con Bitcode.

Importar en Xcode

  • Una vez que tengas el archivo .framework descomprimido, abre tu proyecto en Xcode.
  • Arrastra el archivo .framework al área del navegador del proyecto, preferiblemente dentro del grupo Frameworks.
  • Asegúrate de marcar la opción Copy items if needed.

Configuración del Framework

  • Selecciona tu proyecto en el navegador del proyecto.
  • Selecciona tu target y ve a la pestaña General.
  • Desplázate hacia abajo hasta la sección Frameworks, Libraries, and Embedded Content.
  • Encuentra identiaFlow.framework en la lista y cambia la opción Do Not Embed a Embed & Sign.

Solicitar permisos de cámara

  • Asegúrate de que tu Info.plist para solicitar acceso a la cámara del dispositivo y geolocalización.

NSLocationWhenInUseUsageDescription:

  • Haz clic con el botón derecho en cualquier espacio en blanco dentro del editor de Info.plist.
  • Selecciona Add Row.
  • Introduce NSLocationWhenInUseUsageDescription como la clave.
  • En el tipo, selecciona String.
  • En el valor, introduce un mensaje descriptivo que le dirá al usuario por qué tu aplicación necesita acceso a su ubicación cuando está en uso. Por ejemplo: Necesitamos acceder a tu ubicación para mostrarte lugares cercanos.

NSCameraUsageDescription:

  • De la misma manera, haz clic con el botón derecho y selecciona Add Row.
  • Introduce NSCameraUsageDescription como la clave.
  • En el tipo, selecciona String.
  • En el valor, introduce un mensaje descriptivo que le dirá al usuario por qué tu aplicación necesita acceso a su cámara. Por ejemplo: Necesitamos acceso a tu cámara para que puedas tomar fotos dentro de la app.

Tu archivo Info.plist debería tener ahora algo similar a:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Necesitamos acceder a tu ubicación para ...</string>

<key>NSCameraUsageDescription</key>
<string>Necesitamos acceso a tu cámara para que puedas ...</string>

Uso del SDK

IdentiaFlowView

Este componente es la interfaz principal que deberás implementar en tu aplicación:

IdentiaFlowView(
    idSession: "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx",
    endPoint: "https://apifacialdev.identia.pe/") { jsonString in
    // Aquí puedes manejar el jsonString que se retornó desde el sdk
    print(jsonString)
}

Parámetros

Parámetro Tipo Descripción Obligatorio
idSession String Una cadena que identifica la sesión actual. Debe seguir el formato de dos cadenas hexadecimales de longitud 64 separadas por un punto. Sí
endPoint String URL del servidor. Debe pertenecer al dominio identia.pe. Sí

El SDK de Identia Flow retornará respuestas que tu aplicación debe manejar adecuadamente para proporcionar retroalimentación al usuario.

Personalización gráfica

Para incorporar una personalización de la interfaz en tu implementación, utiliza el parámetro style en el constructor de IdentiaFlowView. El PERSONALIZATION_ID se obtiene directamente del Backoffice. Simplemente asigna este ID de tu personalización a este parámetro, como se muestra en el siguiente ejemplo:

IdentiaFlowView(
    idSession: "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx",
    endPoint: "https://apifacialdev.identia.pe/",
    style: PERSONALIZATION_ID) { jsonString in
    // Aquí puedes manejar el jsonString que se retornó desde el sdk
    print(jsonString)
}

Parámetros adicionales

Parámetro Tipo Descripción Obligatorio
style String ID de personalización obtenido del Backoffice para customizar la interfaz. No

Respuestas del SDK

El closure de IdentiaFlowView entrega un string JSON con el resultado. Según el caso, ese JSON corresponde al flujo biométrico (UI web, campo msg) o a un error nativo del SDK (permiso de cámara o error al procesar la respuesta de la UI, campo message). Esta guía documenta ambos formatos.

El parámetro minimalResponse del constructor controla si la UI puede entregar una respuesta mínima (solo result, msg, id, confidence) en el flujo biométrico.

Cómo recibe la respuesta

En el closure de IdentiaFlowView recibirá un jsonString:

IdentiaFlowView(
    idSession: processId,
    endPoint: "https://apifacialdev.identia.pe/"
) { jsonString in
    // Procesar jsonString (ver formatos siguientes)
}
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 Sin permiso de cámara al abrir, o JSON de la UI no válido 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).

En iOS no hay errores nativos por idSession o endPoint inválidos (a diferencia del SDK Android, que sí los devuelve con códigos 501 y 502).

Dos formatos de respuesta

Respuesta del flujo biométrico Error nativo del SDK
Cuándo Tras usar la UI de verificación Sin cámara autorizada al abrir, o fallo al leer el JSON de la UI
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.

El campo result debe leerse como booleano (true / false), no como texto.

Ejemplo mínimo de recepción:

IdentiaFlowView(idSession: processId, endPoint: endPoint) { jsonString in
    guard let data = jsonString.data(using: .utf8),
          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
    // Flujo biométrico: json["msg"] as? String
    // Error nativo del SDK: json["message"] as? String, json["code"] as? Int
}

Errores nativos del SDK

El SDK genera solo estos JSON en nativo. Siempre incluyen result: false, data: null y no incluyen msg.

code message Cuándo
401 No se tiene permiso a la cámara La cámara no está autorizada al mostrar el flujo
500 Ha ocurrido un error, por favor inténtelo de nuevo más tarde. El JSON recibido desde la UI no es un objeto válido o no se pudo parsear

El texto de message en iOS no es el mismo que en Android (401 con otro mensaje). Conviene mostrar en su app un mensaje propio al usuario y usar code para la lógica.

Sin permiso de cámara (401):

{
  "result": false,
  "message": "No se tiene permiso a la cámara",
  "code": 401,
  "data": null
}

En la primera apertura, si el permiso aún está en estado no determinado, el SDK puede invocar onComplete con este 401 antes de que el usuario responda al diálogo del sistema. Ese callback no implica necesariamente una denegación definitiva: puede volver a presentar IdentiaFlowView después de conceder permiso o revisar AVCaptureDevice.authorizationStatus(for: .video) en su aplicación.

Error al procesar la respuesta de la UI (500):

{
  "result": false,
  "message": "Ha ocurrido un error, por favor inténtelo de nuevo más tarde.",
  "code": 500,
  "data": null
}

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.

Cuándo no se invoca onComplete

El closure puede no ejecutarse si, por ejemplo:

  • El usuario cierra la vista sin que la UI web envíe un mensaje.
  • La UI web no envía ningún JSON al SDK.
  • El JSON recibido no es un objeto con result de tipo booleano (en ese caso el SDK no reenvía el mensaje web mediante el closure).

Si necesita un cierre explícito del flujo en su aplicación, puede combinar el uso del SDK con su propia lógica de cancelación o consulta del proceso en backend cuando corresponda.