Guía de integración de biometría - SDK Web Identia

El SDK Web de Identia se distribuye como una biblioteca de JavaScript disponible desde un CDN. Este documento describe los pasos necesarios para integrar el SDK en tu aplicación web.

Primeros Pasos

Para comenzar la integración, incluye el SDK en tu aplicación web añadiendo la siguiente etiqueta script a tu HTML:

<script src="https://userintegration.apifacialdev.identia.pe/identia.biometria.min.js"></script>

MD5: 01f309b775928a801dc587808f570c26

Importante

La URL proporcionada no debe ser modificada, ya que es la misma para todos los ambientes, ya sea QA o Producción.

Inicialización

Después de incluir el SDK, necesitas inicializarlo especificando un elemento div en el que se mostrará la interfaz de usuario, el ID del proceso de validación (obtenido de las APIs), una función de callback para recibir los datos de la biometría, y el ambiente del sistema biométrico sobre el cual estés trabajando.

Por ejemplo, si tienes un elemento div con el ID biometria, si el ID del proceso de validación entregado por las APIs es aa.12.bb y una función de callback llamada handler_function, puedes inicializar el SDK de la siguiente manera:

IdentiaVerification(
  document.getElementById("biometria"),
  "aa.12.bb",
  handler_function,
  "dev"
);

Importante

Al inicializar el SDK, asegúrate de especificar el ambiente correcto. En el ejemplo anterior, se utiliza "dev" para un ambiente de desarrollo. Si estás trabajando en un ambiente de QA, reemplaza "dev" por "qa". Si el ambiente es de Producción, utiliza "prod".

Esto iniciará el proceso biométrico dentro del elemento div especificado en tu página web.

Personalización gráfica

Si has creado una personalización de la interfaz en el Backoffice, puedes agregarlo mediante el parámetro styleId con el sufijo "&v=2a", simplemente agrega el ID de tu personalización como valor de este parámetro de la siguiente manera

IdentiaVerification(
  document.getElementById("biometria"),
  "aa.12.bb",
  handler_function,
  "dev",
  styleId
);

Manejo de Datos Biométricos

A continuación, se muestra un ejemplo de cómo podría verse tu función de callback (funcion_handler). Esta función será invocada con los datos biométricos al completar el proceso biométrico:

function funcion_handler(data_biometrica) {
  if (data_biometrica.result) {
    console.log("Process successful");
  } else {
    console.log("Process unsuccessful", data_biometrica.msg);
  }
}

Reemplaza "aa.12.bb" con tu verdadero ID de proceso de identificación y funcion_handler con el nombre real de tu función de callback.

Los datos retornados del proceso biométrico estarán estructurados de la siguiente manera:

result: Indica si el proceso biométrico fue exitoso o no.
msg: El mensaje de error asociado con el proceso biométrico cuando result es false. Los diferentes tipos de msg se describen en la siguiente sección.
confidence: El nivel de confianza del proceso biométrico.
proccess_data: Los datos biométricos que fueron capturados asociados con el proceso biométrico.

Ejemplo de los datos biométricos cuando el proceso es no exitoso:

{
   result: false,
   msg: "liveness:selfie",
   confidence: 1
}

Ejemplo de los datos biométricos cuando el proceso es exitoso:

{
   result: true,
   msg: null,
   confidence: 0.96,
   proccess_data: {
       selfie: "base64encodedstring",
       doc: {
           front: "base64encodedstring",
           back: "base64encodedstring"
       }
   }
}

Mensajes informativos durante la validación biométrica

El sistema genera mensajes informativos durante la validación biométrica que pueden ser explotados por los integradores para obtener información de lo que ocurre en el momento en que el usuario final interactúa con el API de biometría.

Estos mensajes se emiten a través del handler function del SDK.
Estos mensajes pueden ser capturados por las integraciones para poder generar indicadores sobre los eventos que ocurren durante los procesos biométricos.
No son de uso obligatorio.

Mensajes generados

Mensaje	Motivo
`selfie:sdk:connection:timeout`	Tiempo de espera excedido durante la operación
`selfie:sdk:camera:empty`	El dispositivo no cumple con los requisitos mínimos de hardware
`selfie:sdk:camera:overconstrained`
`selfie:sdk:camera:Access`	No hay acceso o permisos necesarios para usar la cámara
`selfie:sdk:camera:busy`
`selfie:sdk:camera:abort`
`selfie:sdk:bug`
`selfie:sdk:unknown`	Error no identificado del sistema
`ui:connection:error`	La conexión con internet se interrumpió o es inestable
`process:response:connection:error`
`process:response:connection:timeout`

Otros mensajes relacionados

Mensaje	Motivo
`selfie:assets:timeout`	Este mensaje aparece cuando no cargan todos los recursos que el usuario necesita para pasar por su proceso biométrico en el dispositivo.

Mensajes de Error

Cuando el resultado biométrico se entrega al integrador, la propiedad msg contendrá la causa del error si hay un resultado negativo.

Los diferentes tipos de msg se agrupan en dos categorías: "procesos de identificación no finalizados" e "identificación no superada".

Identificación No Superada

Este grupo de errores se devuelve cuando el proceso de identificación es infructuoso debido a que no se superó uno de los desafíos de identificación.

El msg corresponderá al desafío de identificación fallido.

Ejemplo 1:

{
  msg: "liveness:selfie";
}
Razón: El desafío liveness:selfie no se superó porque el selfie no cumple con el umbral mínimo para la detección de vida

Ejemplo 2:

{
  msg: "match:ocr:id";
}
Razón: El desafío match:ocr:id no se superó porque el OCR del ID no coincide con el valor esperado

Los diferentes tipos de challenges se describen en la documentación de la API.

Procesos de Identificación No Finalizados

Este grupo de errores se devuelve cuando el proceso de identificación es infructuoso debido a un error en el análisis de los datos biométricos.

valor de "msg"	Descripción
no reniec_portrait data	Los datos obtenidos de RENIEC no incluyen el retrato. Ajusta los desafíos a los datos retornados por RENIEC.
no reniec data	No se pudieron obtener los datos de RENIEC. Verifica tu configuración y/o contrato con RENIEC.
selfie not found	Falta el selfie en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
no reniec params	Tus parámetros de RENIEC aún no están configurados. Revisa tu configuración en el backoffice de tu cuenta.
no back doc data	Falta el dato del reverso del documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
no front doc data	Falta el dato del anverso del documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
doc_type not found	El tipo de documento de identidad no existe.
doc not found	Falta el documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
wrong challenge	Uno de los desafíos proporcionados no es válido.
db_write	Error interno. El sistema biométrico podría estar experimentando un problema temporal y no se pudo analizar el proceso de ID.

Ambientes

Al inicializar el SDK, asegúrate de especificar el ambiente correcto como el último parámetro. En el ejemplo anterior, se utiliza "dev" para un ambiente de desarrollo. Reemplaza "dev" por el identificador de tu ambiente objetivo.

Recomendaciones

Permissions-Policy

Si tiene políticas de seguridad en este sentido, debe agregar los orígenes de identia.pe, como se muestra a continuación en el ejemplo:

Permissions-Policy: camera=(self "https://*.identia.pe"), geolocation=(self
"https://*.identia.pe")

Esta configuración permite el uso de la cámara y la geolocalización en su aplicación web únicamente desde el dominio identia.pe y sus subdominios. Asegúrese de ajustar estos parámetros según sus necesidades de seguridad y privacidad.

Integración mediante sdk.

Para garantizar una integración correcta, se debe usar el SDK específico para el sistema operativo correspondiente:

Android: Documentación SDK Android
iOS: Documentación SDK iOS

Importante

Recomendamos considerar que los SDKs están diseñados específicamente para garantizar integraciones fluidas y sin problemas con nuestros servicios para los sistemas operativos Android, iOS y los entornos web. Es importante considerar que TOC no puede dar soporte a integraciones que usen métodos alternativos a los recomendados.