SDK Web

Le SDK web Certivant est un petit script sans dépendance qui ouvre une vérification à l'intérieur de votre page — dans une fenêtre modale ou en ligne dans un conteneur — et indique à votre code quand le demandeur atteint chaque étape et quand il termine. Le demandeur ne quitte jamais votre site, et aucune donnée personnelle ne transite par votre page : le SDK ne transmet qu'un nom d'étape, un statut final et un identifiant public.

Il intègre les mêmes pages hébergées que vous pouvez déjà envoyer par lien :

1. Autoriser votre site web

Les navigateurs n'affichent une page dans un cadre que si le propriétaire de la page y consent. Dans Paramètres → KYC → Intégration, ajoutez les origines des sites web qui l'intégreront, une par ligne :

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

• Une origine correspond à https://hôte suivi, facultativement, d'un :port, sans chemin.
• Un préfixe *. autorise tous les sous-domaines (https://*.example.org), jamais le domaine nu, et jamais un suffixe nu tel que *.com.
• Le protocole http n'est accepté que pour localhost, 127.0.0.1 et [::1].
• Jusqu'à 20 origines. Tout autre site web affiche « refus de connexion ».

2. Créer la vérification

Créez la vérification avec l'API REST et obtenez son jeton hébergé (kvs_…) — voir Sessions. Faites-le sur votre serveur : ne placez jamais une clé d'API dans le navigateur.

3. Ajouter le script et l'ouvrir

<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 du script est l'origine Certivant qu'il encadre. Si vous utilisez un domaine personnalisé, chargez le script depuis celui-ci, ou transmettez origin: "https://id.yourbrand.com".

En ligne

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

Le cadre s'agrandit avec son contenu (événements resize) et ne descend jamais sous minHeight.

Options

Certivant.open() renvoie un descripteur : close() (signale cancel sauf si le parcours est déjà terminé), destroy() (silencieux), on(event, fn), off(event, fn), ainsi que iframe et origin.

Événements

not_ready se déclenche lorsque la page n'a pas signalé ready après 20 secondes. La cause habituelle est que l'origine de votre site ne figure pas dans Intégration, ou que le jeton a déjà été utilisé.

Modèle de sécurité

• Qui peut encadrer une page. Le proxy définit Content-Security-Policy: frame-ancestors 'self' <your origins> (et supprime X-Frame-Options) sur vos liens hébergés, formulaires et pages Live ID. Un jeton inconnu, une erreur ou une liste vide rendent ces pages impossibles à encadrer. Les pages du tableau de bord et de connexion ne sont jamais encadrables.
• En qui le SDK fait confiance. L'URL du cadre n'est construite qu'à partir de l'origine du SDK lui-même, de origin ou de trustedOrigins. Un message n'est accepté que s'il provient de la fenêtre de cet iframe, de l'origine exacte qui a été encadrée, et s'il s'agit d'une enveloppe versionnée { "source": "certivant", "version": 1, … }. Tout le reste est ignoré.
• À qui la page s'adresse. La page encadrée n'envoie de messages qu'à l'origine parente annoncée par le SDK (?parentOrigin=), et seulement lorsque cette origine figure dans votre liste autorisée (ou correspond à l'origine de la page elle-même) et, lorsque le navigateur l'expose, correspond à location.ancestorOrigins. Elle n'utilise jamais de cible *.
• Aucune donnée personnelle. Les événements ne contiennent jamais de noms, de données de documents, de scores ni d'images.

Caméra, microphone et géolocalisation

Le SDK définit allow="camera; microphone; geolocation; clipboard-write" sur l'iframe, ce qui délègue ces autorisations à la page intégrée. La politique Permissions-Policy propre à Certivant les autorise pour ses pages (camera=(self)…), de sorte que les deux côtés sont cohérents. Votre site doit lui-même être servi en HTTPS (ou en localhost), et ne doit pas envoyer d'en-tête Permissions-Policy qui bloque camera ou microphone.

iframe simple

Sans le SDK, vous pouvez utiliser un iframe ordinaire : autorisez d'abord votre origine, puis ajoutez l'attribut 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>

Les événements sont publiés vers le parentOrigin que vous annoncez, s'il est autorisé ; écoutez avec window.addEventListener("message", …) et vérifiez vous-même event.origin, event.source et l'enveloppe.

Dépannage

Gestion des versions

Le script indique sa version dans Certivant.version et dans l'en-tête de réponse X-Certivant-SDK-Version. L'enveloppe des messages porte version: 1 ; les ajouts au sein de la version 1 sont rétrocompatibles, et un changement incompatible sera livré en version 2, la version précédente restant servie. Le chargeur est mis en cache pendant quelques minutes.

Pour les applications natives, voir WebView mobile.