SDK web

El SDK web de Certivant es un pequeño script sin dependencias que abre una verificación dentro de su página, en un modal o en línea dentro de un contenedor, e informa a su código cuando el solicitante llega a cada paso y cuando termina. El solicitante nunca abandona su sitio, y ningún dato personal pasa por su página: el SDK informa únicamente del nombre de un paso, un estado final y un id público.

Incrusta las mismas páginas alojadas que ya puede enviar por enlace:

1. Permita su sitio web

Los navegadores solo muestran una página dentro de un marco cuando el propietario de la página lo acepta. En Configuración → KYC → Integración, añada los orígenes de los sitios web que la incrustarán, uno por línea:

https://app.example.com
https://*.example.org
http://localhost:3000

• Un origen es https://host más un :port opcional, sin ruta.
• Un *. inicial permite todos los subdominios (https://*.example.org), nunca el dominio sin subdominio ni un sufijo genérico como *.com.
• El http simple solo se acepta para localhost, 127.0.0.1 y [::1].
• Hasta 20 orígenes. Cualquier otro sitio web verá «se ha rechazado la conexión».

2. Cree la verificación

Cree la verificación con la API REST y obtenga su token alojado (kvs_…); consulte Sesiones. Hágalo en su servidor: nunca coloque una clave de API en el navegador.

3. Añada el script y ábralo

<script src="https://app.certivant.com/embed/certivant.js"></script>
<button id="verify">Verify my identity</button>
<script>
  document.getElementById("verify").addEventListener("click", function () {
    var flow = Certivant.open({
      token: "kvs_…", // from your server
      onReady: function () { console.log("loaded"); },
      onStep: function (e) { console.log("step", e.step); },
      onComplete: function (e) { console.log("done", e.status, e.requestId); },
      onCancel: function () { console.log("closed"); },
      onError: function (e) { console.error(e.code, e.message); }
    });
  });
</script>

El origen del script es el origen de Certivant que se incrusta. Si usa un dominio personalizado, cargue el script desde él o pase origin: "https://id.yourbrand.com".

En línea

<div id="verification"></div>
<script>
  Certivant.open({
    mode: "inline",
    container: "#verification", // element or selector
    formSlug: "customer-onboarding",
    locale: "fr",
    minHeight: 640
  });
</script>

El marco crece con su contenido (eventos resize) y nunca se reduce por debajo de minHeight.

Opciones

Certivant.open() devuelve un manejador: close() (informa de cancel salvo que el flujo ya se hubiera completado), destroy() (silencioso), on(event, fn), off(event, fn), además de iframe y origin.

Eventos

not_ready se dispara cuando la página no ha indicado ready tras 20 segundos. La causa habitual es que el origen de su sitio web no está en Integración, o que el token ya se ha usado.

Modelo de seguridad

• Quién puede incrustar una página. El proxy establece Content-Security-Policy: frame-ancestors 'self' <your origins> (y elimina X-Frame-Options) en sus enlaces alojados, formularios y páginas de Live ID. Un token desconocido, un error o una lista vacía dejan las páginas sin posibilidad de incrustarse. Las páginas del panel y de inicio de sesión nunca pueden incrustarse.
• En quién confía el SDK. La URL del marco se construye solo a partir del propio origen del SDK, de origin o de trustedOrigins. Un mensaje se acepta solo si proviene de la ventana de ese iframe, del origen exacto que se incrustó, y es un sobre versionado { "source": "certivant", "version": 1, … }. Todo lo demás se ignora.
• Con quién habla la página. La página incrustada envía mensajes solo al origen padre que anunció el SDK (?parentOrigin=), y únicamente cuando ese origen está en su lista de permitidos (o coincide con el origen de la propia página) y, cuando el navegador lo expone, coincide con location.ancestorOrigins. Nunca envía mensajes con destino *.
• Sin datos personales. Los eventos nunca incluyen nombres, datos de documentos, puntuaciones ni imágenes.

Cámara, micrófono y ubicación

El SDK establece allow="camera; microphone; geolocation; clipboard-write" en el iframe, lo que delega esos permisos en la página incrustada. El propio Permissions-Policy de Certivant los permite para sus páginas (camera=(self)…), así que ambos lados coinciden. Su sitio debe servirse él mismo por HTTPS (o localhost), y no debe enviar una cabecera Permissions-Policy que bloquee camera o microphone.

iframe simple

Sin el SDK, puede usar un iframe normal: permita primero su origen y añada el atributo allow:

<iframe
  src="https://app.certivant.com/verify/kvs_…?embed=1&parentOrigin=https%3A%2F%2Fyour-site.example"
  allow="camera; microphone; geolocation; clipboard-write"
  style="width:100%;height:760px;border:0"
></iframe>

Los eventos se envían al parentOrigin que anuncie, si está permitido; escúchelos con window.addEventListener("message", …) y compruebe usted mismo event.origin, event.source y el sobre.

Solución de problemas

Versionado

El script informa de su versión en Certivant.version y en la cabecera de respuesta X-Certivant-SDK-Version. El sobre de los mensajes incluye version: 1; las adiciones dentro de la versión 1 son compatibles hacia atrás, y un cambio incompatible se publica como versión 2 manteniendo servida la versión anterior. El cargador se almacena en caché durante unos minutos.

Para aplicaciones nativas, consulte WebView móvil.