Saltar a contenido

Biometric ID - SDK - IOS

En este documento encontrará una explicación de cómo se realiza la integración con el SDK BiometricID en iOS

Pre requisitos

  • Para hacer uso del SDK debe contar con un API Key válido.
  • El Bundle Identifier debe ser previamente autorizado para activar el uso del SDK

Flujo de uso

El SDK está diseñado para utilizarse de manera secuencial, el flujo es el siguiente:

flowchart LR
    A([Consulta de documento]) --> B([Verificación biometrica])
    B --> C([Consulta de información adicional])

Modo de uso

Existen 2 formas de usar el SDK

  • Haciendo uso de los View predefinidos
  • Haciendo uso de los ViewModel predefindos

Nota

El SDK está diseñado usando el patron MVVM

  • Puede descargar un demo desde acá: Demo.zip

Ejecución del demo

Para correr el proyecto demo incluido en Demo.zip, configure primero las credenciales:

  1. Ubique el archivo Config.xcconfig.example y cópielo con el nombre Config.xcconfig.
  2. Edite Config.xcconfig y reemplace los valores de API_KEY y USER_EMAIL con las credenciales que le fueron proporcionadas.

Nota

El archivo Config.xcconfig está incluido en .gitignore para evitar commitear credenciales. El valor de API_URL ya viene preconfigurado con el endpoint público de la API y normalmente no requiere cambios.

Instalación del SDK

Prerequisitos de instalación

  • Debe descargar el zip con los componentes de instalación Demo.zip

Instalación

Siga estos pasos para instalar (o actualizar) el SDK en su proyecto:

1. Agregue el SDK como dependencia SPM al proyecto.

2. Agregue los Assets (runtime_data) al proyecto.

Arrastre la carpeta de assets runtime_data al proyecto en Xcode.

Importante: los assets deben quedar como file reference individuales

Al agregar los assets, seleccione la opción "Create groups" (grupos amarillos), no "Create folder references" (carpeta azul).

Cada archivo debe quedar referenciado de forma individual como una file reference (icono de grupo amarillo). Si los recursos quedan como una folder reference (carpeta azul), el SDK no podrá localizarlos en tiempo de ejecución y la captura biométrica fallará.

3. Copie los FaceModels a la raíz del target de la aplicación.

Los archivos de modelo facial (FaceModels) deben ubicarse en el nivel raíz del target de la app. Si no se encuentran en esa ubicación, el reconocimiento facial no se inicializará correctamente.

4. Verifique que el SDK esté embebido y firmado.

En Targets → General → Frameworks, Libraries, and Embedded Content, asegúrese de que el SDK aparezca con la opción Embed & Sign. Si está configurado como "Do Not Embed", la aplicación fallará al iniciar por no encontrar el framework.

Actualización del SDK

Para actualizar el SDK a una nueva versión, repita los pasos de instalación:

  1. Actualice la versión de la dependencia SPM.
  2. Vuelva a copiar los assets (runtime_data) respetando que queden como file reference individuales (grupos amarillos, no carpeta azul).
  3. Vuelva a copiar los FaceModels a la raíz del target de la app si cambiaron.
  4. Confirme que el framework permanezca en modo Embed & Sign.

Parametros de configuración

Debe inicializar el SDK con el ApiKey y la Url del api

        let apiUrl = "https://apibiometricid.racsa.go.cr/bioapi"
        let apiKey = ""
        BiometricIdSDK.Initialize(URL: apiUrl, API_KEY: apiKey, SHOW_DEBUG: false)

Views

En caso de hacer uso de las vistas, estas están diseñadas con la siguiente secuencia, sin embargo cada una funciona de manera independiente, permitiendo al desarrollador control en el paso a paso de las vistas.

flowchart LR
    A([DocumentQueryView]) --> B([BiometricQueryView])
    B --> C([BiometricMatchView])

DocumentQueryView

Esta vista permite ingresar los datos de consulta, en Tipo de documento y Número de documento

DocumentQueryView

El constructor de la vista contiene 3 parametros:

  • model

Debe ser de tipo DocumentQueryViewModel

  • onNext

Acción a ser llamada al oprimirse el botón de Continuar

  • content

El contenido entre el TextField de número de documento y el Button de Continuar es un ViewContent que permite ingresar lo que se necesite.

@ObservedObject var documentQueryViewModel = DocumentQueryViewModel()

DocumentQueryView(
    model: documentQueryViewModel,
    onNext:{
        print("onNext")
        //Paso sugerido:
        //Usar documentQueryViewModel.Query para consultar el documento
    })
    {
        VStack{
            Text("Antes de continuar").padding(.bottom, 20)
            Text("Por favor, lea atentamente lo siguiente.\nAl continuar, usted confirma que está de acuerdo con las siguientes declaraciones:").padding(.bottom, 20)
            Link("Ver términos y condiciones", destination: URL(string: "https://biometricid.racsa.go.cr/terminoscondiciones")!).padding(.bottom, 20)
            Text("He leído y estoy de acuerdo con estos términos y condiciones").padding(.bottom, 20)
        }
    }

BiometricQueryView

Esta vista permite iniciar la verificación biometrica por reconocimiento facial o captura de huella según estén disponibles los metodos de validación para el documento consultado.

BiometricQueryView

Info

A partir de esta vista se puede identificar el ID asociado a esta transacción. 

var available = DocumentAvailableResponse()

Nota

DocumentAvailableResponse es la respuesta obtenida al consultar si un documento está disponible para su verificación biometrica usando DocumentQueryViewModel.Query

var biometricQueryViewModel = BiometricQueryViewModel(model: available, documentNumber: documentQueryViewModel.documentNumber, documentType: documentQueryViewModel.documentType))

BiometricQueryView(model: biometricQueryViewModel, onFaceCaptured: { image in
                            //la imagen del rostro fue capturada

                            biometricQueryViewModel.QueryByPhoto(fullFacePhoto: image) { response in
                                //Resultado de verificación biometrica

                                onBiometricQueryResponse(response: response, viewModel: viewModel)
                            }

                        }, onFingerCaptured: { finger , fingerPrint in
                            //la imagen de la huella fue capturada

                            biometricQueryViewModel.QueryByFinger(finger: finger, fingerPrint: fingerPrint) { response in
                                //Resultado de verificación biometrica

                                onBiometricQueryResponse(response: response, viewModel: viewModel)
                            }

                        }, onFaceFailed: { error in
                           //La captura del rostro falló
                        }, onFingerFailed: { error
                            in
                           //La captura de la huella falló
                        })

func onBiometricQueryResponse(response:Result<BiometricVerificationResponseBase?, Error>, viewModel:BiometricQueryViewModel){
    switch response {
    case .success(let data):
        if let match = data as? BiometricVerifiedResponse, match.hit == true
        {
            //La verificación biometrica fue exitosa
            //Paso sugerido, Mostrar resultado en BiometricMatchView
        }else{
            //La verificación biometrica no exitosa
            if(data?.remainingTries ?? 0 <= 0){
                //Se alcanzó el limite de intentos
            }else{
                //Aún cuenta con intentos disponibles
            }
        }
        break;
    case .failure(let error):
        if let validationProblem = error as? ValidationProblemDetails{
            //Ocurrió un error de validación
            if(validationProblem.errors != nil && !validationProblem.errors!.isEmpty){
                //Fallas de validación de entrada
                var message = "";
                validationProblem.errors?.forEach({ key, errors in
                    message += errors.joined(separator: "\n")
                })
            }else {
                //Ocurrió otro error de validación
            }
        } lse if let problem = error as? ProblemDetails {
           //Ocurrió un error en el servidor
        }else{
           //Ocurrió un error inesperado o de red
        }
    }
}

BiometricMatchView

Esta vista permite mostrar el resultado de la verificación biometrica exitosa en un formato estandarizado.

BiometricMatchView 

    var biometricMatchViewModel = BiometricMatchViewModel(
            currentBiometricResult: match,
            currentQuery: biometricQueryViewModel.currentQuery,
            documentNumber: biometricQueryViewModel.documentNumber)

    BiometricMatchView(model: biometricMatchViewModel,
    onFinish: {
        //Acción a ser ejecutada al finalizar el contador de tiempo
    }, 
    onGetMoreInformation: {
       //Acción a ser ejecutada al oprimir el botón de más información
       //Paso suguerido:
       //Mostrar fuentes adicionales disponibles
    })

ViewModels:

DocumentQueryViewModel

  • Query

Metodo que permite ejecutar la consulta de documento.

documentQueryViewModel.Query(completionHandler: { response in
    switch response {
    case .success(let data):
        if let available = data as? DocumentAvailableResponse, available.biometricAvailable == true
        {
            //El número de documento está disponible para su consulta
            //Paso sugerido:
            //Mostrar view para capturar huella o foto del rostro según corresponda.
        }else{
           //El número de documento no está disponible para su verificación
        }

    case .failure(let error):
        if let validationProblem = error as? ValidationProblemDetails{
          //Ocurrio un error de validación de la entrada
        }else if let problem = error as? ProblemDetails {
          //"Ocurrió un error en el servidor")
        }else{
          //Ocurrió un error inesperado
        }
    }
})

BiometricQueryViewModel

  • Constructor

Recibe como modelo la respuesta a la llamada de documentQueryViewModel.Query cuando el documento esta disponible para su consulta.

init(model:DocumentAvailableResponse, 
    documentNumber:String, 
    documentType:DocumentTypeEnumeration)
  • StartFaceCapture

Inicia la camara del dispositivo para el proceso de captura facial.

Nota

Solo funciona en dispositivos fisicos. En caso de usar el SDK para emulador, esta función no ejecuta código

func StartFaceCapture(
        isUseBackCamera:Bool, 
        isAutoCapture:Bool, 
        isFastCapture:Bool, 
        isoEnabled:Bool, 
        isGetFullFrontalCrop:Bool, 
        useCompresion:Bool, 
        onFaceCaptured: @escaping (NSData?,[String],[String]) -> Void,
        onCancelled: @escaping() -> Void,
        onFaceCaptureFailed: @escaping (String) -> Void,
        onTimedout: @escaping (NSData?) -> Void) -> Void
- QueryByPhoto

Ejecuta la consulta de verificación biometrica por rostro usando una imagen en base64

func QueryByPhoto(
    fullFacePhoto:String,
    completionHandler: 
        @escaping (Result< BiometricVerificationResponseBase?, Error>) -> Void
- StartFingerCapture

Inicia la camara del dispositivo para el proceso de captura de huella.

Nota

Solo funciona en dispositivos fisicos. En caso de usar el SDK para emulador, esta función no ejecuta código

func StartFingerCapture(
    finger:Finger,
    onFingersCaptured: @escaping ([CapturedFinger]) -> Void,
    onFingerCaptureFailed: @escaping (String)->Void) -> Void
- QueryByFinger

Ejecuta la consulta de verificación biometrica por huella usando una huella WSQ en base64

func QueryByFinger(
    finger:Finger,
    fingerPrint:String,
    completionHandler: 
        @escaping (Result< BiometricVerificationResponseBase?, Error>) -> Void

BiometricMatchViewModel

  • Constructor

    Recibe el resultado exitoso de una verificación biometrica y el resultado exitoso de la consulta de documento

init(currentBiometricResult: BiometricVerifiedResponse,
    currentQuery:DocumentAvailableResponse,
    documentNumber:String)

Novedades / Historial de versiones

Resumen de las mejoras incluidas en cada versión de la aplicación Biometric ID RACSA.

Versión 1.63 — 25/05/2026

Mejora en la velocidad de captura

Se optimizaron los algoritmos de detección y procesamiento de imagen, reduciendo el tiempo de respuesta entre la colocación del dedo y la confirmación de captura exitosa.

Opción para captura de forma vertical

Se activa la posibilidad de captura de los dedos desde el frente del dispositivo, aumentando el área de captura en la pantalla. Se permite la captura únicamente en modo vertical (Portrait).

Versión 1.60 — 30/04/2026

Mejora en la velocidad de captura

Aumento en la rapidez de la autocaptura de huellas. Se mantienen las guías visuales de posicionamiento del dedo en pantalla durante todo el proceso.

Validación cantidad de dígitos tanto para Cédula como para DIMEX

La consulta de Nacionales exige 9 caracteres (cédula) y la de Extranjeros 12 caracteres (DIMEX) antes de iniciar la transacción, evitando errores por datos incompletos.

Tiempo de inactividad de sesión ampliado

El inicio de sesión permanece activo hasta 8 horas de inactividad antes de solicitar nuevamente las credenciales por seguridad.