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.

A partir de la versión 0.0.8 el SDK también permite la lectura NFC del chip de documentos de identidad compatibles con el estándar ICAO 9303 (pasaportes, cédulas y permisos de residencia electrónicos), cuando el proceso lo requiere.

Versión actual: 0.0.8
Formato .xcframework (device + simulador)
Compilado con Xcode 26.2
iOS mínimo 15.6
Dependencias OpenSSL.xcframework 3.6.2000 (se distribuye junto al SDK)
Bitcode No aplica

Novedades respecto a 0.0.7

  • Lectura NFC de documentos ICAO 9303. Requiere configuración adicional en el proyecto (ver Configuración para NFC).
  • Respuestas normalizadas en msg. Los errores propios del SDK ya no se entregan en un campo message con texto en español: ahora usan msg con un identificador, igual que las respuestas del flujo biométrico y que los SDK de Android y Web (ver Errores nativos del SDK).
  • El permiso de cámara se solicita desde el SDK, y el 401 se entrega solo ante una denegación definitiva (ver Sin permiso de cámara).
  • El SDK ya no muestra mensajes de error en pantalla. Se eliminaron los textos que presentaba ante un error nativo: ahora invoca onComplete, cierra la vista y devuelve el control a su aplicación, para que usted decida qué mostrar (ver Su aplicación debe reaccionar al closure).
  • Toda respuesta devuelve el control a su aplicación. Una respuesta que el SDK no puede interpretar ya no deja la vista abierta sin aviso: ahora se informa como sdk:response:invalid y la vista se cierra igual que en cualquier otro cierre.
  • Distribución como .xcframework, que incluye los slices de dispositivo y de simulador. Ya no se distribuye .framework.
  • Se incorpora OpenSSL.xcframework como dependencia obligatoria.
  • Se elimina la variante con Bitcode. Apple descontinuó Bitcode a partir de Xcode 14 y las versiones actuales de las herramientas ya no lo generan, por lo que ahora existe una única compilación por versión.
  • Verificación por SHA-256 en lugar de MD5.

Cambios incompatibles al actualizar desde 0.0.7

Respuestas de error. Si su integración leía el campo message de los errores nativos, debe pasar a leer msg. Los code de iOS no cambian (401, 403, 500); lo que cambia es el campo y el valor, que ahora son identificadores compartidos con Android. Las respuestas del flujo biométrico no cambian.

Pantalla de error. Donde antes el SDK dibujaba un texto de error y permanecía en pantalla, ahora no dibuja nada y solicita cerrarse. Si su aplicación no retira la vista al recibir onComplete, el usuario quedará ante una pantalla en blanco: revise Su aplicación debe reaccionar al closure.

La lectura NFC requiere un dispositivo físico

El simulador de iOS no dispone de hardware NFC. El SDK compila y se ejecuta con normalidad en el simulador, pero al iniciar una lectura NFC devolverá un error indicando que la funcionalidad no está disponible.

Cómo Integrar el SDK

Descarga del SDK

El SDK se distribuye como dos archivos .zip que deben descomprimirse antes de agregarlos al proyecto. Ambos son obligatorios.

Para verificar la integridad de los archivos descargados:

shasum -a 256 identiaFlow.xcframework.zip
shasum -a 256 openssl.zip

El resultado debe coincidir exactamente con los valores indicados arriba.

Sobre OpenSSL

identiaFlow.xcframework enlaza OpenSSL de forma dinámica. Si OpenSSL.xcframework no está incorporado en la aplicación, el proyecto compilará sin errores pero la aplicación fallará al iniciarse con un mensaje similar a:

dyld: Library not loaded: @rpath/OpenSSL.framework/OpenSSL

Utilice siempre la versión de OpenSSL publicada junto a la misma versión del SDK. Una versión distinta produce el mismo fallo.

El paquete de OpenSSL incluye su archivo LICENSE.txt (Apache License 2.0) y un README.md con la información de origen y su suma de verificación. Ambos archivos deben conservarse junto al framework.

Importar en Xcode

  • Descomprima ambos archivos .zip.
  • Abra su proyecto en Xcode.
  • Arrastre identiaFlow.xcframework y OpenSSL.xcframework al área del navegador del proyecto, preferiblemente dentro del grupo Frameworks.
  • Asegúrese de marcar la opción Copy items if needed.

Configuración del Framework

  • Seleccione su proyecto en el navegador del proyecto.
  • Seleccione su target y vaya a la pestaña General.
  • Desplácese hasta la sección Frameworks, Libraries, and Embedded Content.
  • Localice identiaFlow.xcframework y OpenSSL.xcframework en la lista y cambie en ambos la opción Do Not Embed a Embed & Sign.

Configuración para NFC

Estos pasos solo son necesarios si su proceso incluye la lectura NFC del documento. Si los omite, el resto del flujo biométrico funcionará con normalidad.

1. Habilitar la capacidad NFC

  • Seleccione su target y vaya a la pestaña Signing & Capabilities.
  • Pulse + Capability y agregue Near Field Communication Tag Reading.

Esta capacidad también debe estar habilitada en el App ID correspondiente dentro del portal de Apple Developer; de lo contrario el perfil de aprovisionamiento no la incluirá.

Xcode agregará la siguiente clave al archivo .entitlements de la aplicación:

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

2. Declarar el identificador de aplicación del documento

Agregue la siguiente clave a su archivo Info.plist:

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
</array>

Esta clave va en Info.plist, no en el archivo .entitlements

A pesar del prefijo com.apple.developer.*, esta clave no es un entitlement. iOS la utiliza durante la detección del chip para seleccionar la aplicación del documento.

Si falta, el sistema mostrará normalmente el diálogo "Acerque su iPhone al documento", pero el documento nunca será detectado y la sesión terminará por tiempo de espera sin ningún mensaje que indique la causa.

3. Agregar la descripción de uso de NFC

En el mismo Info.plist:

<key>NFCReaderUsageDescription</key>
<string>Necesitamos acceso a NFC para leer el chip de su documento de identidad.</string>

Solicitar permisos de cámara

  • Asegúrese de configurar su Info.plist para solicitar acceso a la cámara del dispositivo y geolocalización.

NSLocationWhenInUseUsageDescription:

  • Haga clic con el botón derecho en cualquier espacio en blanco dentro del editor de Info.plist.
  • Seleccione Add Row.
  • Introduzca NSLocationWhenInUseUsageDescription como la clave.
  • En el tipo, seleccione String.
  • En el valor, introduzca un mensaje descriptivo que le indicará al usuario por qué su 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, haga clic con el botón derecho y seleccione Add Row.
  • Introduzca NSCameraUsageDescription como la clave.
  • En el tipo, seleccione String.
  • En el valor, introduzca un mensaje descriptivo que le indicará al usuario por qué su 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.

Resumen del Info.plist

Con la lectura NFC habilitada, su archivo Info.plist debería incluir 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>

<key>NFCReaderUsageDescription</key>
<string>Necesitamos acceso a NFC para leer el chip de su documento de identidad.</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
</array>

Uso del SDK

IdentiaFlowView

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

IdentiaFlowView(
    idSession: "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx",
    endPoint: "https://apifacialdev.identia.pe/") { jsonString in
    // Aquí puede 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. Sí
endPoint String URL del servidor. Debe usar https y pertenecer al dominio identia.pe. Sí

Validación del endPoint

Desde la versión 0.0.8 el SDK valida el endPoint antes de cargar el flujo. Si la URL no usa https o su dominio no pertenece a identia.pe, el SDK no carga nada y devuelve un error nativo con code 403 (ver Errores nativos del SDK).

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

Personalización gráfica

Para incorporar una personalización de la interfaz en su implementación, utilice el parámetro style en el constructor de IdentiaFlowView. El PERSONALIZATION_ID se obtiene directamente del Backoffice. Simplemente asigne este ID de su 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í puede 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. Por defecto, "". No
minimalResponse Bool Solicita una respuesta mínima (solo result, msg, id y confidence) en el flujo biométrico. Por defecto, false. No

Respuestas del SDK

El closure de IdentiaFlowView entrega un string JSON con el resultado. Desde la versión 0.0.8, todas las respuestas —las del flujo biométrico y los errores propios del SDK— usan el mismo campo de motivo: msg.

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

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)
}

Toda respuesta comparte la misma forma:

Campo Contenido
result true o false
msg Identificador del motivo
code Código asociado al motivo
data Puede incluir process_data u omitirse; siempre null en los errores nativos

El origen se distingue por el valor de msg, no por el campo: los que empiezan por sdk: los genera el propio SDK; el resto proviene del flujo biométrico y está documentado en el Catálogo de mensajes.

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 }
    let msg = json["msg"] as? String ?? ""
    let code = json["code"] as? Int

    if msg.hasPrefix("sdk:") {
        // Error nativo del SDK: configuración de la integración o permisos.
    } else {
        // Resultado del flujo biométrico.
    }
}

Su aplicación debe reaccionar al closure

Cuando el proceso termina —por éxito, por rechazo o por un error nativo—, el SDK invoca onComplete y solicita el cierre de IdentiaFlowView. A partir de ese momento el SDK no muestra nada: no presenta mensajes de error ni pantallas de reintento.

Ese cierre se resuelve a través del entorno de presentación de SwiftUI, de modo que solo surte efecto si IdentiaFlowView fue presentada por su aplicación (con sheet, fullScreenCover, o insertada en una pila de navegación).

Si incrusta la vista sin presentarla, verá una pantalla en blanco

Si IdentiaFlowView es la vista raíz de su aplicación, o está incrustada directamente en la jerarquía sin haber sido presentada, la petición de cierre no tiene efecto. Como el SDK ya no muestra ningún texto, el usuario quedaría ante una pantalla en blanco.

En ese caso, la navegación es responsabilidad de su aplicación: use el closure para retirar la vista y mostrar su propia pantalla de resultado.

struct VerificacionView: View {
    @State private var mostrarFlujo = false
    @State private var resultado: String?

    var body: some View {
        Button("Verificar identidad") { mostrarFlujo = true }
            .fullScreenCover(isPresented: $mostrarFlujo) {
                IdentiaFlowView(idSession: processId, endPoint: endPoint) { jsonString in
                    resultado = jsonString
                    // Retire la vista desde su propio estado: no dependa únicamente
                    // del cierre que solicita el SDK.
                    mostrarFlujo = false
                }
            }
    }
}

Errores nativos del SDK

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

msg code Cuándo
sdk:camera:denied 401 El usuario denegó el permiso de cámara solicitado por el SDK, o estaba denegado o restringido por el sistema
sdk:endpoint:invalid 403 El endPoint no usa https o su dominio no pertenece a identia.pe
sdk:response:invalid 500 La respuesta recibida del flujo no se pudo interpretar: no es un objeto válido, o no trae un campo result booleano

Estos identificadores son los mismos en Android y en iOS, con el mismo code, de modo que su backend puede tratarlos con una sola lógica.

El SDK no muestra ningún mensaje al usuario

Ante cualquier error, el SDK no presenta avisos ni pantallas de error: invoca onComplete con la respuesta, cierra IdentiaFlowView —igual que al terminar el flujo biométrico— y devuelve el control a su aplicación. Qué se le muestra al usuario, y si conviene reintentar, lo decide usted a partir del msg.

Sin permiso de cámara:

{
  "result": false,
  "msg": "sdk:camera:denied",
  "code": 401,
  "data": null
}

IdentiaFlowView comprueba el permiso al aparecer y, si el usuario aún no ha decidido, muestra el diálogo del sistema para solicitarlo. Su aplicación no necesita pedirlo por adelantado; sí debe declarar NSCameraUsageDescription en el Info.plist (ver Solicitar permisos de cámara), sin lo cual iOS cierra la aplicación al presentar el diálogo.

El 401 se entrega solo cuando la denegación es definitiva: el usuario rechaza el diálogo, o el permiso ya estaba denegado o restringido por el sistema. Mientras el diálogo está en pantalla el SDK no invoca onComplete, de modo que puede tratar este 401 como un resultado terminal.

endPoint no permitido:

{
  "result": false,
  "msg": "sdk:endpoint:invalid",
  "code": 403,
  "data": null
}

Este error indica un problema de configuración de la integración, no una acción del usuario: reintentar no lo resolverá. Verifique que el endPoint use https y pertenezca al dominio identia.pe.

Error al procesar la respuesta del flujo:

{
  "result": false,
  "msg": "sdk:response:invalid",
  "code": 500,
  "data": null
}

Errores de la lectura NFC

Los errores de la lectura NFC no son errores nativos del SDK: su msg no lleva el prefijo sdk: ni los code de la tabla anterior. Llegan al closure como una respuesta del flujo biométrico, con el prefijo nfc:sdk:.

Un error de lectura aborta la captura: el SDK entrega el resultado a su aplicación y cierra la vista, sin reintentar dentro del mismo flujo. Por ejemplo, un documento retirado del lector antes de que la lectura termine produce:

{
  "result": false,
  "msg": "nfc:sdk:client:document",
  "code": 400
}

Abortar la captura no resuelve el proceso de validación

Estas respuestas interrumpen la captura, pero no dan por finalizado el proceso de validación de identidad ni consumen un intento. Un proceso solo se resuelve cuando las capturas llegan completas al backend y este determina si la persona fue validada o no.

El listado completo de valores está en el Catálogo de mensajes.

Si la lectura NFC nunca llega a iniciarse y en la consola de Xcode aparece un mensaje con el prefijo ### IdentiaFlow NFC misconfiguration:, se trata de un problema de configuración del proyecto: revise la sección Configuración para NFC.

Flujo biométrico (respuesta con msg)

Cuando el usuario completa o interrumpe la verificación, 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.

Referencias:

Ejemplo de rechazo biométrico:

{
  "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 el usuario abandona la vista sin que el SDK haya recibido ninguna respuesta: por ejemplo, si descarta la presentación deslizando hacia abajo.

En cambio, toda respuesta que el SDK sí recibe produce siempre una llamada al closure, aunque no pueda interpretarla: en ese caso la informa como sdk:response:invalid.

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.

Versiones anteriores

Versiones sin mantenimiento

Las versiones listadas a continuación se conservan únicamente como referencia para integraciones existentes. No incluyen lectura NFC ni las validaciones incorporadas en 0.0.8. Para nuevas integraciones utilice siempre la versión actual.

0.0.7

Se distribuía como archivo .framework (salvo la compilación para Xcode 16.4) y en dos variantes, con y sin Bitcode. Estas versiones no requieren OpenSSL.xcframework.

Con Bitcode:

Sin Bitcode:

Migración de 0.0.7 a 0.0.8

  • Reemplace identiaFlow.framework por identiaFlow.xcframework y agregue OpenSSL.xcframework, ambos con Embed & Sign.
  • Si utilizaba la variante con Bitcode, no existe equivalente: utilice la única compilación disponible.
  • Verifique que el endPoint use https y pertenezca al dominio identia.pe; en caso contrario recibirá el error 403.
  • Si su proceso incluye lectura NFC, complete la Configuración para NFC.