Captura web

Lleva a la persona por la captura en un navegador, usando el token y el enlace que devuelve Human Plugin.

Markdown

Tu back-end crea el proceso en Human Plugin con un flujo Journey. La respuesta 201 trae tres valores que el front-end necesita:

Campo	Se usa para
id	El id del proceso en Human Plugin. El SDK lo recibe como transactionId, y tu back-end lee el resultado con él
token	Inicia la captura en el Journeys SDK
link	La página de captura alojada

token y link se devuelven solo en la creación. Pásalos al front-end en la misma solicitud o guárdalos tú mismo. Consulta Human Token Journey.

Requisitos

La captura se ejecuta en el navegador y necesita acceso a la cámara.

SO	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• Las páginas deben servirse por HTTPS. La cámara solo funciona en un contexto seguro.
• La navegación dentro de apps requiere Android 8 (API 26) o iOS 13 o superior.
• No se admiten los navegadores integrados en apps de redes sociales.

Elige un modelo

Modelo	Ideal para
Enlace alojado	La configuración más simple. Sin biblioteca: la persona va al link y vuelve a tu callbackUri
Journeys SDK	La captura se abre dentro de tu página, así que la persona nunca la abandona

Enlace alojado

Envía callbackUri en la solicitud de creación. Es la página a la que vuelve la persona cuando termina la captura.

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

Luego envía a la persona al link, de una de dos maneras:

• Redirección. Navega al link. Al final, la persona regresa a callbackUri.
• Nueva pestaña. Abre el link con window.open(), observa cuándo la pestaña llega a callbackUri y ciérrala.

Cuando la persona vuelva, avisa a tu back-end, que llama a GET /v1/processes/{id}.

Journeys SDK

El SDK abre la captura en un iFrame dentro de tu página. Funciona con cualquier framework (React, Angular, Vue) o con JavaScript puro.

Antes de empezar, pide al soporte de Unico que registre tus dominios. Deben usar HTTPS.

1. Instala

npm install unico-journey-sdk

El SDK sigue el versionado semántico, así que las actualizaciones menores y de parche son seguras. Mantenlo al día: las correcciones de seguridad y de errores se publican en versiones nuevas.

2. Permite el SDK en tus encabezados

Omite este paso si tu página no envía los encabezados Content-Security-Policy ni Permissions-Policy. De lo contrario, agrega:

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io"),
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io")

3. Inicializa

Llama a init en cuanto sepas que la captura será necesaria. Precarga la captura.

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. Abre la captura

Parámetro	Obligatorio	Valor
transactionId	Sí	El id de Human Plugin
token	Sí	El token de la creación
onFinish	Sí	Se llama cuando la captura termina o la persona la cierra
onWidgetVisibilityChange	No	Se llama cuando la captura se muestra u oculta

ByUnicoSDK.open({
  transactionId: id, // el id de Human Plugin
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // La captura terminó. Pide a tu back-end que lea el resultado.
    }
    // type === 'CLOSE': la persona la cerró antes del final.
  },
  // Opcional: oculta tus propios overlays mientras la captura está visible.
  onWidgetVisibilityChange: (visible) => {},
});

// Para cerrarla tú mismo:
ByUnicoSDK.close();

onFinish recibe:

Campo	Descripción
type	'FINISH' cuando la captura terminó, 'CLOSE' cuando la persona la cerró antes
transaction.redirectUrl	A dónde enviar a la persona después. Presente solo con 'FINISH'

advertencia

onFinish indica que la captura terminó, no cómo. El resultado proviene únicamente de GET /v1/processes/{id} en tu back-end.

Usa también onFinish para llevar a la persona a la siguiente pantalla y para evitar crear de inmediato un proceso nuevo si vuelve a empezar.

Solución de problemas

• El flujo se interrumpe o se comporta de forma extraña. Asegúrate de que ningún script tuyo modifique el iFrame del SDK en el DOM.
• La captura se ve diferente. Las reglas CSS amplias, como los selectores de etiqueta, pueden alcanzar el iFrame. Los ids y clases propios del SDK empiezan con unico.
• Errores inesperados después de una actualización. Instala el SDK solo mediante npm o yarn, y nunca edites sus archivos.

Pruebas

Cierra las DevTools del navegador antes de probar una captura de extremo a extremo. Unas DevTools abiertas bloquean el envío.

Configuraciones no compatibles

• El SDK dentro de un WebView móvil. En una app, abre el link. Consulta las guías de Android, iOS, Ionic, React Native y Flutter.
• Tu propio <iframe> apuntando a la captura. Usa el SDK, que administra el iFrame.