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

Aviso de versión

Los siguientes pasos corresponden a la versión de 2026-07-10. La versión anterior sigue vigente y pueden ver más información en el siguiente enlace.

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.apifacial.identia.pe/identia-biometria/v2.0/identia.biometria.min.js"
  integrity="sha256-H0vPnCrqvsqrLoE7bcKBItDoXIZebZzEwWuZdj1q7ps="
  crossorigin="anonymous"></script>

Hash de integridad (SHA256): sha256-H0vPnCrqvsqrLoE7bcKBItDoXIZebZzEwWuZdj1q7ps=

El navegador verifica automáticamente este hash mediante Subresource Integrity (SRI): al cargar el script, calcula el SHA256 del archivo descargado y lo compara con el valor de integrity; si no coinciden, bloquea la ejecución.

Importante

Los atributos integrity y crossorigin="anonymous" son obligatorios: sin crossorigin="anonymous", el navegador bloquea el script al validar integrity. El hash SHA256 lo genera y publica Identia por versión; no debe calcularlo ni modificarlo, solo copiarlo tal cual. La URL tampoco debe modificarse: 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.

Sintaxis

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

Parámetros

Parámetro	Tipo	Descripción	Valores posibles	Obligatorio
`element`	`HTMLElement`	Elemento DOM donde se renderizará la interfaz del SDK.	Cualquier `<div>` válido	Sí
`processId`	`String`	ID del proceso de validación obtenido de las APIs.	Formato: `aa.12.bb`	Sí
`callback`	`Function`	Función que se invocará con los datos biométricos al completar el proceso.	Función JavaScript válida	Sí
`environment`	`String`	Ambiente del sistema biométrico.	`"dev"`, `"qa"`, `"prod"`	Sí
`styleId`	`String`	ID de personalización gráfica obtenido del Backoffice (opcional, usar con sufijo `&v=2a`).	ID de personalización	No

Ejemplo básico

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 agregarla 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
);

Respuestas del proceso biométrico

Cómo recibe la respuesta

La función de callback que se entrega a IdentiaVerification será invocada cuando el proceso biométrico tenga una respuesta final o un error entregable para el integrador. El SDK renderiza la experiencia en un iframe; cuando la interfaz interna finaliza, envía la respuesta al sitio integrador y el SDK ejecuta el callback con el objeto JSON correspondiente. También puede recibir el JSON vía postMessage al embeber el iframe.

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

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.

Estructura y mensajes de la respuesta

Estructura de las respuestas JSON: campos, respuesta completa, respuesta mínima y process_data.
Catálogo de mensajes (msg) y ejemplos: valores de msg, code y ejemplos de payload.

Mensajes informativos durante la validación biométrica

El sistema genera mensajes informativos durante la validación biométrica que pueden ser utilizados por los integradores para obtener información de lo que ocurre mientras el usuario final interactúa con el flujo. No siempre implican el fin del proceso; para respuestas finales, consulte el catálogo de mensajes.

Características:

Estos mensajes se emiten a través de la función handler del SDK.
Pueden ser capturados por las integraciones para 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:camera:freshness_timeout`	Error durante la captura de la selfie
`selfie:sdk:camera:face_distance`
`selfie:sdk:camera:multiple_faces`
`selfie:sdk:camera:landscape`
`selfie:sdk:camera:framerate`
`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.

Ambientes

Al inicializar el SDK, asegúrate de especificar el ambiente correcto como el cuarto parámetro.

Ambiente	Valor	Descripción
Desarrollo	`"dev"`	Ambiente para desarrollo y pruebas iniciales.
QA	`"qa"`	Ambiente de control de calidad para pruebas.
Producción	`"prod"`	Ambiente de producción para uso final.

Reemplaza "dev" por el identificador de tu ambiente objetivo.

Recomendaciones

Content-Security-Policy (CSP)

Puedes aplicar una política CSP estricta, sin necesidad de la excepción 'unsafe-eval':

script-src 'self' https://userintegration.apifacial.identia.pe 'nonce-{nonce}';

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 nativo

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

Plataforma	Enlace a documentación
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.