Documentación de Auvral

Integra el flujo de verificación de Auvral en tu página: instalación, callbacks y la única regla que importa.

El SDK web de Auvral monta el flujo de verificación alojado en una capa sobre tu página, te avisa cuando termina y se quita solo.

No maneja llaves de API, no crea sesiones y no habla con la API de Auvral. Todo lo que necesita viaja en la url que tu backend ya obtuvo de POST /v1/sessions.

Míralo funcionando primero

Pruébalo abre este mismo SDK contra una sesión de sandbox, así que puedes ver los callbacks dispararse antes de integrar nada.

Instalación

<script src="https://sdk.dev.auvral.com/v1/verification.js"></script>

Un script sin dependencias que define un solo global, window.AuvralVerification.

Sandbox y producción

El snippet de arriba es la URL de sandbox. En producción, cárgalo desde

<script src="https://sdk.auvral.com/v1/verification.js"></script>

/v1/ sigue el último lanzamiento de la versión mayor actual y es seguro depender de ella directamente. Para fijar un lanzamiento exacto, nombra su versión en lugar de v1: esa ruta nunca cambia de bytes una vez publicada, así que es segura de verificar con Subresource Integrity. Versiones del SDK lista cada versión publicada con un snippet <script src integrity> copiable.

Crea la sesión con `allowedOrigins`

El SDK recibe su resultado del flujo de verificación, que solo lo enviará a una página cuyo origen la sesión permita explícitamente. Esa lista viene de tu backend, cuando creas la sesión:

server.js

const res = await fetch(`${process.env.AUVRAL_API_URL}/v1/sessions`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.AUVRAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    flowId: process.env.AUVRAL_FLOW_ID,
    referenceId: user.id,
    allowedOrigins: ["https://app.example.com"], // la página que integrará el flujo
  }),
});

La URL base de la API en este ambiente es https://api.dev.auvral.com

Omitir allowedOrigins rompe los callbacks del SDK, en silencio

Si dejas el campo fuera, la lista queda vacía, así que ningún origen coincide nunca y no se envía nada. onResult y onClose no se disparan jamás, y el indicador de carga nunca se quita.

No falla nada en la red, la verificación se completa normalmente y tu webhook llega a tiempo: solo el lado del navegador se queda callado. El flujo embebido escribe un aviso [auvral] en la consola del navegador, y ese aviso es el único lugar donde esta falla se nombra.

Es opcional en el esquema de la API y no es opcional en la práctica. Pasa el origen exacto de la página que integra el flujo (esquema, host y puerto, sin ruta) en cada integración embebida: una entrada que no es un origen responde 400 INVALID_ALLOWED_ORIGINS nombrándola, así que la única falla que queda por detectar a ojo es un origen bien formado que no es el de la página que integra.

Todos los orígenes, a propósito

allowedOrigins: ["*"] está soportado y significa exactamente lo que dice: el flujo envía su resultado a cualquier página que lo integre. Úsalo cuando el origen que integra no se puede saber al crear la sesión: un tenant en su propio dominio, una agencia que corre el flujo para sus clientes, o localhost en el puerto que haya elegido tu servidor de desarrollo.

Es todo o nada: ["*"] no se puede combinar con un origen concreto, y una lista que los mezcla responde 400 INVALID_ALLOWED_ORIGINS nombrando ambos, porque piden cosas opuestas.

A cambio, cualquier página que tenga la URL de la sesión recibe los eventos de esa sesión, así que la garantía dura lo que dure la URL. Eso es poco: el código que lleva es de un solo uso, lo emite tu backend con tu llave secreta y queda atado al primer dispositivo que lo abre. Prefiere la lista explícita siempre que puedas escribirla.

Úsalo

const auvral = new AuvralVerification();

const frame = auvral.init({
  url: sessionUrl,
  onResult: ({ status, verificationId, sessionId }) => {
    // status es "verified" o "rejected"
  },
  onClose: ({ reason }) => {},
  onError: ({ code, message }) => {},
});

init() devuelve un manejador:

frame.close();  // desmonta, idempotente
frame.isOpen;   // booleano

No hay un componente de botón de Auvral. Conecta el tuyo, así combina con tu sistema de diseño:

<button id="verify">Verificar identidad</button>
<script>
  document.getElementById("verify").onclick = async () => {
    const { url } = await (await fetch("/verification/start", { method: "POST" })).json();
    new AuvralVerification().init({ url, onResult: console.log });
  };
</script>

Qué significan los callbacks

onResult se dispara apenas hay un veredicto, y no cierra la capa. Tu usuario puede seguir leyendo la pantalla final. Aprovecha ese margen: actualiza la página detrás de él, habilita un botón, empieza lo que sigue.

onClose no significa que la verificación terminó. Un cierre sin un onResult previo significa que tu usuario se fue antes. Volver a abrir la misma url retoma donde se quedó, mientras la sesión siga viva. Si le ofreces eso o no, lo decides tú.

Por defecto el SDK dibuja su propio botón de cerrar para que un usuario nunca quede atrapado detrás de una capa a pantalla completa. Pasa dismissible: false para quitarlo.

La regla que importa

El postMessage es una señal de interfaz, no una prueba

Nunca desbloquees una cuenta, apruebes un pago o cambies el estado de tu negocio a partir de él. La verdad es el webhook o un GET del lado del servidor. Vive en el navegador, y el usuario controla su navegador.

onResult llega en el navegador de tu usuario, en una página donde puede abrir las herramientas de desarrollo. Cualquiera puede llamar a tu callback con status: "verified" desde la consola. El SDK rechaza los mensajes que no vengan del flujo de verificación mismo, lo que impide que otro código de tu página falsifique un resultado. No puede hacer nada respecto a la persona frente al teclado.

Entonces:

Usa onResult para la interfaz. Una pantalla de éxito, el siguiente paso de tu asistente, un indicador de carga mientras tu backend se pone al día.
Usa el webhook para la decisión. Estado de la cuenta, pagos, límites, permisos.

Un buen patrón es que onResult consulte a tu propio backend, que reporta éxito solo una vez que tu manejador de webhooks ya corrió.

Antes de depurar cualquier cosa

Si la capa no aparece o la cámara nunca se enciende, casi siempre es un header de tu propia página. Lee primero Requisitos del navegador.

Referencia del SDK: cada opción, callback y código de error.
Versiones del SDK: cada versión publicada, su hash integrity y cómo fijarla con SRI.
Requisitos del navegador: CSP, Permissions-Policy, HTTPS.
Webhooks: el resultado autoritativo.

SDK web