Web-SDK

Das Certivant Web-SDK ist ein kleines, abhängigkeitsfreies Script, das eine Verifizierung innerhalb Ihrer Seite öffnet — als Modal oder inline in einem Container — und Ihrem Code mitteilt, wann der Antragsteller jeden Schritt erreicht und wann er fertig ist. Der Antragsteller verlässt Ihre Website nie, und über Ihre Seite gehen niemals personenbezogene Daten: Das SDK meldet einen Schrittnamen, einen Endstatus und eine öffentliche ID.

Es bettet dieselben gehosteten Seiten ein, die Sie bereits per Link versenden können:

1. Ihre Website freigeben

Browser zeigen eine Seite nur dann in einem Frame an, wenn der Eigentümer der Seite zustimmt. Fügen Sie unter Einstellungen → KYC → Einbettung die Origins der Websites hinzu, die sie einbetten werden — einen pro Zeile:

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

• Ein Origin ist https://host mit optionalem :port, ohne Pfad.
• Ein vorangestelltes *. erlaubt jede Subdomain (https://*.example.org), niemals die nackte Domain und niemals ein nacktes Suffix wie *.com.
• Einfaches http ist nur für localhost, 127.0.0.1 und [::1] akzeptiert.
• Bis zu 20 Origins. Jede andere Website zeigt „verweigert die Verbindung“.

2. Die Verifizierung erstellen

Erstellen Sie die Verifizierung mit der REST-API und erhalten Sie ihr gehostetes Token (kvs_…) — siehe Sitzungen. Tun Sie dies auf Ihrem Server: Legen Sie niemals einen API-Schlüssel in den Browser.

3. Das Script einbinden und öffnen

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

Der Origin des Scripts ist der Certivant-Origin, den es einrahmt. Verwenden Sie eine eigene Domain, laden Sie das Script von dort oder übergeben Sie origin: "https://id.yourbrand.com".

Inline

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

Der Frame wächst mit seinem Inhalt (Ereignisse resize) und schrumpft nie unter minHeight.

Optionen

Certivant.open() liefert ein Handle: close() (meldet cancel, sofern der Ablauf nicht bereits abgeschlossen ist), destroy() (still), on(event, fn), off(event, fn) sowie iframe und origin.

Ereignisse

not_ready wird ausgelöst, wenn die Seite nach 20 Sekunden nicht ready gemeldet hat. Die übliche Ursache ist, dass der Origin Ihrer Website nicht unter Einbettung steht oder das Token bereits verwendet wurde.

Sicherheitsmodell

• Wer eine Seite einrahmen darf. Der Proxy setzt auf Ihren gehosteten Links, Formularen und Live-ID-Seiten Content-Security-Policy: frame-ancestors 'self' <your origins> (und entfernt X-Frame-Options). Ein unbekanntes Token, ein Fehler oder eine leere Liste lassen sie nicht einrahmbar. Dashboard- und Anmeldeseiten sind nie einrahmbar.
• Wem das SDK vertraut. Die URL des Frames wird nur aus dem eigenen Origin des SDK, aus origin oder aus trustedOrigins gebildet. Eine Nachricht wird nur akzeptiert, wenn sie vom Fenster genau dieses iframes stammt, vom exakten Origin, der eingerahmt wurde, und ein versioniertes Envelope { "source": "certivant", "version": 1, … } ist. Alles andere wird ignoriert.
• Mit wem die Seite spricht. Die eingerahmte Seite sendet nur an den übergeordneten Origin, den das SDK angekündigt hat (?parentOrigin=), und nur wenn dieser Origin in Ihrer Erlaubnisliste steht (oder dem eigenen Origin der Seite entspricht) und, sofern der Browser ihn bereitstellt, mit location.ancestorOrigins übereinstimmt. Es wird nie mit dem Ziel * gesendet.
• Keine personenbezogenen Daten. Ereignisse enthalten nie Namen, Dokumentdaten, Scores oder Bilder.

Kamera, Mikrofon und Standort

Das SDK setzt auf dem iframe allow="camera; microphone; geolocation; clipboard-write", wodurch diese Berechtigungen an die eingebettete Seite delegiert werden. Die eigene Permissions-Policy von Certivant erlaubt sie für ihre Seiten (camera=(self)…), sodass beide Seiten übereinstimmen. Ihre Website selbst muss über HTTPS (oder localhost) ausgeliefert werden und darf keinen Permissions-Policy-Header senden, der camera oder microphone blockiert.

Einfaches iframe

Ohne das SDK können Sie ein normales iframe verwenden — erlauben Sie zuerst Ihren Origin und fügen Sie das Attribut allow hinzu:

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

Ereignisse werden an das von Ihnen angekündigte parentOrigin gesendet, sofern es erlaubt ist. Hören Sie mit window.addEventListener("message", …) zu und prüfen Sie selbst event.origin, event.source und das Envelope.

Fehlerbehebung

Versionierung

Das Script meldet seine Version in Certivant.version und im Antwort-Header X-Certivant-SDK-Version. Das Nachrichten-Envelope trägt version: 1; Ergänzungen innerhalb von Version 1 sind abwärtskompatibel, und eine inkompatible Änderung erscheint als Version 2, wobei die vorherige Version weiterhin ausgeliefert wird. Der Loader wird für einige Minuten zwischengespeichert.

Für native Apps siehe Mobile WebView.