Intégration d'application Web
Cette page décrit le fonctionnement des journeys Unico et les modèles d'intégration disponibles pour les intégrer dans une application.
Un journey est l'ensemble des étapes que l'utilisateur parcourt pour compléter une vérification d'identité. Par exemple : capturer une photo de document et effectuer une capture faciale (liveness).
Unico gère l'ensemble de l'expérience. L'effort d'intégration est minimal : le journey est créé via CreateProcess, l'utilisateur y est dirigé, et le résultat est reçu à la fin. Tout ce qui se trouve entre les deux — écrans, instructions, validations — est déjà construit et maintenu par Unico.
Deux modèles d'intégration
Chaque client a des besoins différents. Unico propose deux modèles pour diriger l'utilisateur vers le journey.
| Modèle | Idéal pour |
|---|---|
| Accès direct | Applications mobiles utilisant déjà une WebView, ou flux web où le journey peut se dérouler en dehors de la page principale |
| Journeys SDK | Applications web nécessitant une expérience intégrée et fluide, gardant l'utilisateur dans le même environnement |
- Accès direct
- Journeys SDK
L'utilisateur est redirigé vers un lien hébergé par Unico, où se déroule le journey. À la fin,
il est renvoyé vers l'URL définie lors de la création du processus (le paramètre callbackUri).
C'est l'approche la plus simple à adopter : elle ne nécessite aucune installation de bibliothèque et fonctionne bien lorsque le journey n'a pas besoin de se dérouler dans la propre page de l'application. En revanche, sortir l'utilisateur de l'environnement du client tend à introduire plus de friction et, par conséquent, un taux d'abandon plus élevé.
Après la création d'un processus, la réponse de l'API inclut l'URL du journey hébergé par Unico. Il existe deux façons courantes de diriger l'utilisateur :
- Redirection standard. L'utilisateur est redirigé directement vers l'URL du journey. À la fin,
Unico le redirige vers le
callbackUridéfini lors de la création du processus. - Nouvel onglet avec
window.open(). Le journey est ouvert dans un nouvel onglet du navigateur, gardant l'utilisateur dans un contexte séparé. Dans ce cas, il est recommandé de surveiller un changement d'URL vers lecallbackUriet de fermer l'onglet une fois le processus terminé. Consultez la documentation MDN pour les détails sur l'API.
Dans les applications mobiles, il est courant d'utiliser une WebView pour ouvrir le journey directement, sans
redirection supplémentaire nécessaire. Dans ce cas, le callbackUri accepte également un deeplink, permettant
à la fin du journey de déclencher l'ouverture d'un écran spécifique dans l'application native.
Il suffit de configurer le deeplink comme destination de retour et le système d'exploitation se charge de diriger
l'utilisateur au bon endroit.
Le journey se déroule au sein de l'application elle-même, sans sortir l'utilisateur de son contexte. Le Journeys SDK est installé dans l'application et utilisé pour ouvrir le journey quand nécessaire.
C'est le chemin recommandé pour une expérience plus intégrée et fluide, gardant l'utilisateur dans le même environnement tout au long, ce qui tend à réduire la friction et l'abandon dans le flux.
Unico fournit une bibliothèque JavaScript compatible avec les navigateurs modernes, permettant d'intégrer le journey dans pratiquement n'importe quelle application avec seulement quelques lignes de code.
Compatibilité
La bibliothèque est conçue pour s'intégrer dans n'importe quel projet sans friction, quel que soit le stack utilisé :
- Toute application web. Distribuée au format UMD, elle fonctionne lorsqu'elle est importée via des bundlers modernes (comme webpack ou Vite). Compatible avec n'importe quel framework (React, Angular, Vue) ou JavaScript pur.
- Navigateurs modernes. La bibliothèque inclut déjà les polyfills nécessaires pour des fonctionnalités comme
les Promises et
async/await, étendant la compatibilité aux anciennes versions de navigateurs également. - APIs web standard. Le journey fonctionne sur les capacités natives du navigateur, sans dépendance à des plugins ou des bibliothèques externes dans le projet.
Comment le SDK fonctionne en interne
Lorsqu'un journey est ouvert, le SDK insère un iFrame dans la page et prend le contrôle de l'expérience visuelle complète à partir de ce point. Les écrans, scripts et ressources de chaque étape s'exécutent à l'intérieur de cet iFrame, du moment où l'utilisateur commence jusqu'à la fin du processus.
Cette décision architecturale est intentionnelle : l'isolation de l'iFrame garantit que le journey Unico n'interfère pas avec les styles ou le comportement de l'application. Aucun script ne fuit dans le contexte externe, aucune règle CSS n'entre en collision avec les propres styles de l'application. Le résultat est une expérience cohérente pour l'utilisateur final et un impact minimal sur le produit du client.
Puisque Unico est responsable de la création et de la gestion de l'iFrame, les améliorations du journey — que ce soit en performance, expérience ou validation — sont livrées automatiquement à tous les utilisateurs, sans changement requis dans l'application intégrée. L'intégration fonctionnera toujours avec les meilleures optimisations disponibles, sans avoir besoin de suivre ou de réagir à chaque mise à jour de la plateforme.
Premiers pas
Étape 1 — Installation
Le package idpay-b2b-sdk est partagé entre les journeys de paiement IDPay et les journeys de vérification
d'identité. Pour les cas d'utilisation d'identité, importez la classe ByUnicoSDK comme indiqué dans les étapes ci-dessous.
npm install idpay-b2b-sdk
La méthode recommandée pour installer le Journeys SDK est via un gestionnaire de packages comme npm ou yarn, à partir du package disponible sur le npm registry. En plus de simplifier l'installation et la gestion des dépendances, cette approche offre un contrôle clair sur la version en cours d'utilisation et facilite la mise à jour lors de la publication d'une nouvelle version.
Le SDK suit le Semantic Versioning (SemVer), ce qui signifie que les mises à jour de correctifs et mineures n'introduisent pas de changements majeurs. Il est sûr de configurer le projet pour recevoir ces mises à jour automatiquement. Les changements pouvant nécessiter des mises à jour d'intégration sont réservés aux versions majeures et sont toujours accompagnés d'un guide de migration.
Rester sur la dernière version est particulièrement important pour deux raisons. La première est la sécurité : les correctifs de sécurité sont publiés chaque fois que des vulnérabilités sont identifiées ou que des opportunités de renforcer le protocole de communication se présentent. Utiliser une version obsolète signifie manquer ces correctifs et exposer le flux à des risques inutiles. La seconde est la stabilité : les corrections de bugs sont distribuées de la même manière, et les versions plus anciennes peuvent présenter des comportements déjà résolus dans les versions plus récentes.
Avant de commencer, enregistrez vos domaines auprès de l'équipe support Unico. Tous les domaines doivent utiliser HTTPS.
Étape 2 — Configurer CSP et Permissions-Policy
Si votre page envoie déjà des en-têtes Content-Security-Policy ou Permissions-Policy, ajoutez les directives suivantes pour que l'iFrame, les scripts et l'accès à la caméra du SDK fonctionnent correctement.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Si votre page n'envoie pas d'en-têtes CSP ou Permissions-Policy, vous pouvez ignorer cette étape — le navigateur n'applique aucune restriction par défaut.
Étape 3 — Appeler init(options)
Initialise le SDK et précharge les scripts nécessaires au bon fonctionnement du journey, créant une expérience plus fluide pour l'utilisateur final. Appelez ceci le plus tôt possible dans le flux.
| Paramètre | Requis | Description |
|---|---|---|
token | Oui | Token du processus retourné par l'API Create Process |
env | Non | Définir à 'uat' uniquement pour les environnements de test |
import { ByUnicoSDK } from 'idpay-b2b-sdk';
ByUnicoSDK.init({
token,
// env: 'uat' // only for test environments
});
Étape 4 — Appeler open(options)
Affiche l'iFrame et démarre le journey pour l'utilisateur. À partir de ce point, tout se passe automatiquement à l'intérieur de l'iFrame, sans besoin de gérer aucune étape intermédiaire.
| Paramètre | Requis | Description |
|---|---|---|
transactionId | Oui | ID du processus retourné par l'API Create Process |
token | Oui | Token du processus retourné par l'API Create Process |
onFinish | Oui | Callback exécuté lorsque le journey se termine ou est fermé |
onWidgetVisibilityChange | Non | Callback exécuté lorsque l'état de visibilité du widget change |
L'interaction suivante avec l'application se produit lorsque le journey se termine, que l'utilisateur l'ait
complété ou fermé. À ce moment, le SDK invoque le callback onFinish, passé en paramètre dans open.
À partir de là, l'application peut appeler l'API getProcess pour vérifier le résultat, ou attendre
une notification Webhook si une approche asynchrone est préférée.
En plus de consulter le résultat, il est recommandé d'utiliser onFinish pour gérer l'état du
frontend de l'application :
- Éviter les boucles. Empêcher la recréation immédiate et inutile de processus si l'utilisateur déclenche à nouveau le flux juste après la fin du journey.
- Gestion du flux. S'assurer que l'utilisateur est dirigé vers l'étape suivante de l'application, en évitant un écran en impasse après la fermeture du journey.
Le callback onFinish signale que l'utilisateur a terminé le journey, mais ne garantit pas
l'approbation. Le processus peut s'être terminé par un échec sur l'une des règles de validation Unico.
Interroger via getProcess ou recevoir la notification Webhook n'est pas optionnel : ce sont les
seules sources du résultat réel, et le comportement de l'application doit être basé dessus. onFinish
ne doit pas être utilisé isolément pour déterminer si un utilisateur a été approuvé.
Le callback onFinish reçoit un objet décrivant comment le journey s'est terminé :
| Champ | Type | Description |
|---|---|---|
type | string | Comment le journey s'est terminé : 'FINISH' (terminé) ou 'CLOSE' (l'utilisateur a fermé avant de finir) |
transaction | object | undefined | Présent lorsque type est 'FINISH' ; undefined lorsque type est 'CLOSE' |
transaction.id | string | Identifiant du processus (identique au transactionId fourni) |
transaction.redirectUrl | string | URL pour rediriger l'utilisateur après le journey |
La gestion du callback onWidgetVisibilityChange est optionnelle et peut ne pas être pertinente pour votre
cas d'utilisation. Il est invoqué chaque fois que l'état de visibilité du widget change, et n'est utile que dans un
scénario spécifique : certains journeys affichent un arrière-plan transparent, gardant la page de l'application
visible derrière l'expérience. Les applications qui affichent un modal personnalisé pendant le flux de vérification
(par exemple, dans le cadre d'une orchestration entre plusieurs fournisseurs KYC) peuvent finir par afficher
ce modal derrière le widget Unico, dégradant l'expérience visuelle. Dans ce cas, le callback
permet à l'application de supprimer tout élément visuel supplémentaire pendant que le journey Unico est actif,
et de les restaurer une fois qu'il se termine. Si votre application n'a pas d'interface utilisateur susceptible de chevaucher le widget,
vous pouvez l'omettre en toute sécurité.
ByUnicoSDK.open({
transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
onFinish: ({ transaction, type }) => {
if (type === 'FINISH') {
// Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
}
// type === 'CLOSE' → user closed before finishing;
},
// Optional: only needed if your app shows UI that could overlap the widget.
onWidgetVisibilityChange: (visible) => {
// suppress or restore your modal based on widget visibility
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
Le diagramme de séquence ci-dessous montre comment utiliser le SDK et le résultat de l'API pour configurer l'iFrame :
Applications d'exemple
| Langage / Framework | Description | Dépôt |
|---|---|---|
| Angular | PoC en Angular implémentant le Journeys SDK | GitHub — unico-cbu-poc-angular |
| JS Vanilla | PoC en JS Vanilla implémentant le Journeys SDK | GitHub — unico-cbu-poc-js |
| React | PoC en React implémentant le Journeys SDK | GitHub — unico-cbu-poc-react |
| Vue JS | PoC en Vue JS implémentant le Journeys SDK | GitHub — unico-cbu-poc-vuejs |
Sécurité
La sécurité dans ce modèle est construite en couches, en commençant par le protocole de communication entre le SDK et l'application qui s'exécute à l'intérieur de l'iFrame.
Lorsque le journey est chargé, les deux parties effectuent un handshake pour établir la communication. Dans
ce processus, l'application Unico valide l'origine du message d'injection de données reçu via postMessage
par rapport à une liste fermée de domaines autorisés, segmentée par environnement (UAT et PROD). Les messages
provenant d'origines non approuvées sont immédiatement rejetés, empêchant le journey d'être intégré dans
des pages non autorisées et éliminant la surface d'attaque pour des vulnérabilités telles que le clickjacking.
En plus de la validation de l'origine, le flux ne se poursuit qu'avec un jeton de transaction valide : un JWT à usage unique, émis et signé par le backend Unico. Cela garantit que même une origine autorisée ne peut pas opérer avec un jeton expiré, réutilisé ou falsifié.
Après le handshake, le jeton est injecté dans l'iFrame et aucune information sensible ne circule entre les deux parties. Toute communication restante sert uniquement au contrôle de l'interface — ouverture, fermeture et transitions d'écran — empêchant les données du processus d'être interceptées ou divulguées pendant le journey.
L'isolation de l'iFrame protège également l'intégrité des scripts Unico en cours d'exécution. Puisque le code s'exécute dans un contexte séparé de la page, il ne peut pas être accédé ou modifié par des scripts externes, garantissant que le journey s'exécute exactement comme prévu, sans interférence.
CSP et Permissions-Policy
Si votre page envoie des en-têtes Content-Security-Policy ou Permissions-Policy, assurez-vous que les directives suivantes sont présentes pour que l'iFrame, les scripts et l'accès à la caméra du SDK fonctionnent correctement.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Si votre page n'envoie pas ces en-têtes, le navigateur n'applique aucune restriction par défaut et aucune configuration n'est nécessaire.
Dépannage spécifique au SDK
Cette section couvre les problèmes les plus courants rencontrés lors de l'intégration et les méthodes recommandées pour les investiguer.
Comportement inattendu ou flux interrompu
Vérifiez si un script de l'application manipule directement l'iFrame dans le DOM. Le SDK
crée et gère l'iFrame dans le body de la page, et toute modification externe — que ce soit au
scope, au positionnement ou aux attributs — peut interférer avec le cycle de vie du journey et causer
un comportement imprévisible.
Expérience visuelle différente de celle attendue
Vérifiez si une feuille de style globale de l'application surcharge des propriétés à l'intérieur de l'iFrame.
Le SDK crée l'iFrame et tous ses éléments internes avec des ID dynamiques et des classes préfixées par
unico, ce qui réduit considérablement le risque de conflit via les sélecteurs d'ID ou de classe. Néanmoins,
des règles CSS larges — comme les sélecteurs de balise — peuvent atteindre des éléments à l'intérieur de l'iFrame et altérer
l'expérience visuelle livrée à l'utilisateur.
Fichiers de la bibliothèque SDK modifiés directement
Vérifiez si un fichier de la bibliothèque a été modifié en dehors du gestionnaire de packages. La bibliothèque doit être gérée exclusivement via npm ou yarn, sans modifications directes des fichiers installés. Les modifications manuelles peuvent produire un comportement anormal difficile à reproduire et empêcheront le support Unico de pouvoir vous assister.
Ne gardez pas les DevTools ouvertes pendant les tests de capture
L'application Unico utilise le Capture SDK (unico-webframe) pour la capture faciale, qui détecte les DevTools ouvertes comme un signal potentiel de fraude et bloque la soumission. Fermez les DevTools avant d'exécuter des tests de capture de bout en bout.
Les modèles décrits dans cette documentation — accès direct et Journeys SDK — sont les seules approches d'intégration officiellement supportées par Unico. Les intégrations qui s'écartent de ces standards peuvent causer des comportements inattendus, des échecs de flux de sécurité et des interruptions de journey, et ne seront pas couvertes par le support Unico.
Exemples d'approches non supportées :
- Intégrer le SDK dans une WebView dans les applications mobiles. Dans ces cas, l'approche correcte est d'utiliser le modèle d'accès direct, en ouvrant le lien du journey directement dans la WebView sans impliquer le Journeys SDK.
- Charger l'iFrame directement via une balise HTML
<iframe>, sans passer par le Journeys SDK. L'iFrame est un détail d'implémentation interne du SDK et ne doit pas être instancié manuellement. L'approche correcte est d'utiliser le Journeys SDK, qui gère le cycle de vie de l'iFrame de manière sécurisée et dans les standards attendus.
En cas de doute sur la conformité d'une approche avec le standard supporté, consultez la documentation ou contactez le support avant de procéder à l'implémentation.