Web SDK

Il Web SDK di Certivant è un piccolo script senza dipendenze che apre una verifica all'interno della Sua pagina — in una modale oppure incorporata in un contenitore — e comunica al Suo codice quando il richiedente raggiunge ciascun passaggio e quando termina. Il richiedente non lascia mai il Suo sito, e nessun dato personale passa mai dalla Sua pagina: l'SDK riporta il nome di un passaggio, uno stato finale e un ID pubblico.

Incorpora le stesse pagine ospitate che può già inviare tramite link:

1. Autorizzi il Suo sito web

I browser mostrano una pagina in un frame solo quando il proprietario della pagina è d'accordo. In Impostazioni → KYC → Integrazione aggiunga le origini dei siti web che la incorporeranno — una per riga:

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

• Un'origine è https://host più una eventuale :porta, senza percorso.
• Un *. iniziale autorizza ogni sottodominio (https://*.example.org), mai il dominio nudo né un suffisso nudo come *.com.
• Il protocollo http è accettato solo per localhost, 127.0.0.1 e [::1].
• Fino a 20 origini. Qualunque altro sito web vede "rifiuto di connessione".

2. Crei la verifica

Crei la verifica con la REST API e ne ottenga il token ospitato (kvs_…) — vedi Sessioni. Lo faccia sul Suo server: non inserisca mai una chiave API nel browser.

3. Aggiunga lo script e lo apra

<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>

L'origine dello script è l'origine di Certivant che viene incorporata. Se usa un dominio personalizzato, carichi lo script da esso oppure passi origin: "https://id.yourbrand.com".

In linea

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

Il frame cresce con il proprio contenuto (eventi resize) e non scende mai sotto minHeight.

Opzioni

Certivant.open() restituisce un handle: close() (segnala cancel a meno che il flusso non sia già completato), destroy() (silenzioso), on(event, fn), off(event, fn), più iframe e origin.

Eventi

not_ready si attiva quando la pagina non ha segnalato ready entro 20 secondi. La causa più comune è che l'origine del Suo sito non è presente in Integrazione, oppure che il token è già stato usato.

Modello di sicurezza

• Chi può incorporare una pagina. Il proxy imposta Content-Security-Policy: frame-ancestors 'self' <le Sue origini> (e rimuove X-Frame-Options) sui Suoi link ospitati, sui moduli e sulle pagine Live ID. Un token sconosciuto, un errore o un elenco vuoto lasciano le pagine non incorporabili. Le pagine della dashboard e di accesso non sono mai incorporabili.
• Di chi si fida l'SDK. L'URL del frame è costruito solo a partire dall'origine dell'SDK, da origin o da trustedOrigins. Un messaggio viene accettato solo se proviene dalla finestra di quell'iframe, dall'origine esatta che è stata incorporata, e ha la forma versionata di busta { "source": "certivant", "version": 1, … }. Tutto il resto viene ignorato.
• Con chi comunica la pagina. La pagina incorporata invia messaggi solo all'origine genitore annunciata dall'SDK (?parentOrigin=), e solo quando quell'origine è nel Suo elenco consentito (oppure coincide con l'origine della pagina stessa) e, dove il browser la espone, corrisponde a location.ancestorOrigins. Non usa mai un destinatario *.
• Nessun dato personale. Gli eventi non includono mai nomi, dati dei documenti, punteggi o immagini.

Fotocamera, microfono e posizione

L'SDK imposta allow="camera; microphone; geolocation; clipboard-write" sull'iframe, delegando tali permessi alla pagina incorporata. La Permissions-Policy di Certivant li consente per le proprie pagine (camera=(self)…), quindi i due lati sono coerenti. Il Suo sito deve essere servito in HTTPS (oppure su localhost), e non deve inviare un header Permissions-Policy che blocchi camera o microphone.

iframe semplice

Senza l'SDK può usare un normale iframe — autorizzi prima la Sua origine e aggiunga l'attributo 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>

Gli eventi vengono inviati al parentOrigin che annuncia, se è consentito; si metta in ascolto con window.addEventListener("message", …) e verifichi da sé event.origin, event.source e la busta.

Risoluzione dei problemi

Versioni

Lo script riporta la propria versione in Certivant.version e nell'header di risposta X-Certivant-SDK-Version. La busta dei messaggi contiene version: 1; le aggiunte all'interno della versione 1 sono retrocompatibili, e una modifica non compatibile viene rilasciata come versione 2 mantenendo servita la versione precedente. Il loader viene memorizzato nella cache per alcuni minuti.

Per le app native vedi WebView mobile.