--- title: Intégration d'application Web description: Comment intégrer le contrat Web & SDK côté client — flux de redirection et configuration du SDK iFrame. canonical: https://developer.unico.io/fr/developers/sdks-and-tools/web/ locale: fr generated_by: markdown-export --- - [/fr/](/fr/) - [SDKs et outils](/fr/developers/sdks-and-tools/overview) - Intégration Web App **Sur cette page# Intégration d'application Web Cette page décrit le fonctionnement des parcours Unico et les modèles d'intégration disponibles pour les intégrer à une application. Un **parcours** est l'ensemble des étapes que l'utilisateur suit pour réaliser une vérification d'identité. Par exemple : capturer une photo du document et effectuer une capture faciale (Détection de Vie). Unico prend en charge toute l'expérience. L'effort d'intégration est minimal : le parcours est créé via **CreateProcess**, l'utilisateur y est dirigé et, à la fin, le résultat est reçu. Tout ce qui se passe entre les deux (écrans, instructions, validations) est déjà prêt 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 parcours. ModèleIdéal pour**SDK de Parcours**Applications web nécessitant une expérience intégrée et fluide, gardant l'utilisateur dans le même environnement**Accès direct**Flux web où le parcours peut se dérouler en dehors de la page principale, ou applications qui intègrent déjà une WebView. Les applications natives devraient préférer le SDK de la plateforme Applications nativesSi votre application est une application mobile native, nous recommandons d'utiliser le SDK de la plateforme sur laquelle elle est développée ([Android](/fr/developers/sdks-and-tools/android/requirements), [iOS](/fr/developers/sdks-and-tools/ios/requirements) ou [Flutter](/fr/developers/sdks-and-tools/flutter/requirements)) plutôt qu'une intégration web. SDK de ParcoursAccès directLe parcours se déroule **à l'intérieur de l'application elle-même**, sans sortir l'utilisateur de son contexte. Le **SDK de Parcours** est installé dans l'application et utilisé pour ouvrir le parcours en cas de besoin.C'est la voie recommandée pour une expérience plus intégrée et fluide, qui maintient l'utilisateur dans le même environnement tout au long du processus, ce qui tend à réduire la friction et l'abandon au fil du flux.Unico fournit une bibliothèque JavaScript compatible avec les navigateurs modernes, permettant d'intégrer le parcours dans pratiquement n'importe quelle application en quelques lignes de code.### Compatibilité​ La bibliothèque est conçue pour s'intégrer à n'importe quel projet sans friction, quelle que soit la stack utilisée : **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 avec du 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é également aux versions plus anciennes des navigateurs. **API web standard.** Le parcours s'appuie sur les capacités natives du navigateur, sans dépendre de plugins ni de bibliothèques externes dans le projet. ### Fonctionnement interne du SDK​ À l'ouverture d'un parcours, le SDK insère un iFrame dans la page et prend le contrôle de toute l'expérience visuelle à partir de ce moment. Les écrans, les scripts et les assets de chaque étape s'exécutent à l'intérieur de cet iFrame, depuis le moment où l'utilisateur commence jusqu'à l'achèvement du processus.Ce choix d'architecture est intentionnel : l'isolation de l'iFrame garantit que le parcours Unico n'interfère ni avec les styles ni avec le comportement de l'application. Aucun script ne fuit vers le contexte externe, aucune règle CSS n'entre en conflit avec les 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.Comme Unico est responsable de la création et de la gestion de l'iFrame, les améliorations du parcours (qu'elles concernent les performances, l'expérience ou la validation) sont livrées automatiquement à tous les utilisateurs, sans aucune modification requise dans l'application intégrée. L'intégration fonctionnera toujours avec les meilleures optimisations disponibles, sans avoir à suivre chaque évolution de la plateforme ni à y réagir.### Premiers pas​ **Étape 1** : InstallationLe paquet `unico-journey-sdk` est partagé entre les parcours de paiement IDPay et les parcours de vérification d'identité. Pour les cas d'usage d'identité, importez la classe `ByUnicoSDK` comme indiqué dans les étapes ci-dessous.``` npm install unico-journey-sdk ``` Anciennement idpay-b2b-sdkCe paquet était auparavant publié sous le nom `idpay-b2b-sdk`. Il s'agit du même SDK sous un nouveau nom et il conserve la même ligne de versions. Seules les versions **2.3.0 et ultérieures** sont disponibles sous le nouveau nom — consultez les [Notes de version](/fr/developers/sdks-and-tools/web/resources/release-notes) pour l'historique complet.La méthode recommandée pour installer le SDK de Parcours est via un gestionnaire de dépendances tel que **npm** ou **yarn**, à partir du paquet 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 utilisée et facilite la mise à jour dès qu'une nouvelle version est publiée.Le SDK suit le **versionnage sémantique (SemVer)**, ce qui signifie que les mises à jour de patch et mineures n'introduisent pas de changements incompatibles. Il est sûr de configurer le projet pour recevoir ces mises à jour automatiquement. Les changements susceptibles de nécessiter des adaptations de l'intégration sont réservés aux versions majeures et s'accompagnent toujours d'un guide de migration.Maintenez le SDK à jourRester sur la version la plus récente est particulièrement important pour deux raisons. La première est la **sécurité** : des 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 revient à renoncer à 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 anciennes versions 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 de support Unico. Tous les domaines doivent utiliser HTTPS.**Étape 2** : Appeler `init(options)`Initialise le SDK et précharge les scripts nécessaires au bon fonctionnement du parcours, offrant une expérience plus fluide à l'utilisateur final. Appelez-le le plus tôt possible dans le flux.ParamètreRequisDescription`token`OuiJeton du processus renvoyé par l'API Create Process`env`NonDéfinir sur `'uat'` uniquement pour les environnements de test``` import { ByUnicoSDK } from 'unico-journey-sdk';ByUnicoSDK.init({ token, // env: 'uat' // uniquement pour les environnements de test}); ``` **Étape 3** : Appeler `open(options)`Affiche l'iFrame et démarre le parcours pour l'utilisateur. À partir de ce point, tout se passe automatiquement à l'intérieur de l'iFrame, sans avoir à gérer aucune étape intermédiaire.ParamètreRequisDescription`transactionId`OuiID du processus renvoyé par l'API Create Process`token`OuiJeton du processus renvoyé par l'API Create Process`onFinish`OuiCallback exécuté lorsque le parcours se termine ou est fermé`onWidgetVisibilityChange`NonCallback exécuté lorsque l'état de visibilité du widget changeL'interaction suivante avec l'application se produit lorsque le parcours se termine, que l'utilisateur l'ait achevé ou fermé. À ce moment-là, 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 front-end de l'application : **Éviter les boucles.** Empêcher la recréation immédiate et inutile de processus si l'utilisateur relance le flux juste après la fin du parcours. **Gestion du flux.** Veiller à ce que l'utilisateur soit dirigé vers l'étape suivante de l'application, en évitant qu'il reste bloqué sur un écran sans issue après la fermeture du parcours. avertissementLe callback `onFinish` indique que l'utilisateur a terminé le parcours, mais ne garantit pas l'approbation. Le processus peut s'être terminé par un échec sur l'une des règles de validation d'Unico. Consulter 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 s'appuyer sur elles. `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 parcours s'est terminé :ChampTypeDescription`type`stringComment le parcours s'est terminé : `'FINISH'` (terminé) ou `'CLOSE'` (l'utilisateur a fermé avant la fin)`transaction`object | undefinedPrésent lorsque `type` vaut `'FINISH'` ; `undefined` lorsque `type` vaut `'CLOSE'``transaction.id`stringIdentifiant du processus (le même `transactionId` fourni)`transaction.​redirectUrl`stringURL vers laquelle rediriger l'utilisateur après le parcoursLa gestion du callback **`onWidgetVisibilityChange`** est facultative et peut ne pas être pertinente pour votre cas d'usage. Il est invoqué chaque fois que l'état de visibilité du widget change, et n'est utile que dans un scénario précis : certains parcours affichent un fond transparent, laissant la page de l'application visible derrière l'expérience. Les applications qui affichent une modale personnalisée pendant le flux de vérification (par exemple, dans le cadre d'une orchestration entre plusieurs fournisseurs de KYC) peuvent finir par afficher cette modale 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 tant que le parcours Unico est actif, puis de le restaurer une fois celui-ci terminé. Si votre application n'a aucune interface susceptible de chevaucher le widget, vous pouvez l'omettre sans problème.``` ByUnicoSDK.open({ transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf', token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', onFinish: ({ transaction, type }) => { if (type === 'FINISH') { // Parcours terminé (transaction = { id, redirectUrl }) : poursuivez votre flux ici. } // type === 'CLOSE' → l'utilisateur a fermé avant la fin ; }, // Facultatif : nécessaire uniquement si votre application affiche une interface pouvant chevaucher le widget. onWidgetVisibilityChange: (visible) => { // masquez ou restaurez votre modale selon la visibilité du widget },});// Pour fermer le SDK explicitement à tout moment :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 :### Application de référence​ Langage / FrameworkDescriptionDépôtNode.js (Express)Application de référence en Node.js qui met en œuvre le parcours utilisateur complet avec le Journeys SDK[GitHub — reference-apps/web](https://github.com/unico-labs/reference-apps/tree/main/web)### Sécurité​ La sécurité dans ce modèle est construite par couches, en commençant par le protocole de communication entre le SDK et l'application exécutée à l'intérieur de l'iFrame.Au chargement du parcours, les deux parties effectuent un **handshake** pour établir la communication. Au cours de 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 homologuées sont immédiatement rejetés, ce qui empêche l'intégration du parcours dans des pages non autorisées et élimine la surface d'attaque pour des vulnérabilités telles que le **clickjacking**.Outre 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 d'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 plus aucune information sensible ne circule entre les deux parties. Toute la communication restante ne sert qu'au contrôle de l'interface (ouverture, fermeture et transitions d'écran), empêchant l'interception ou la fuite des données du processus pendant le parcours.L'isolation de l'iFrame protège également l'intégrité des scripts Unico à l'exécution. Comme le code s'exécute dans un contexte séparé de la page, il ne peut être ni consulté ni modifié par des scripts externes, ce qui garantit que le parcours s'exécute exactement tel qu'il a été conçu, sans interférence.Par conception, la CSP n'est pas adoptée dans ce modèle d'intégration. Les domaines autorisés font partie de la configuration de sécurité de chaque client, et leur exposition publique dans les en-têtes pourrait faciliter la cartographie de l'infrastructure par des acteurs malveillants. Comme l'identification du client n'a lieu qu'au moment de l'`init`, il n'est pas possible d'injecter dynamiquement ces domaines dans les en-têtes avant ce point, ce qui rend la CSP inapplicable sans renoncer à cette confidentialité. Toutes les garanties de sécurité sont fournies par le protocole de handshake décrit ci-dessus.### Dépannage spécifique au SDK​ Cette section couvre les problèmes les plus courants rencontrés lors de l'intégration ainsi que les moyens recommandés 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 (de portée, de positionnement ou d'attributs) peut interférer avec le cycle de vie du parcours et provoquer un comportement imprévisible.#### Expérience visuelle différente de celle attendue​ Vérifiez si une feuille de style globale de l'application remplace 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 des sélecteurs d'ID ou de classe. Néanmoins, des règles CSS de portée large (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 du SDK modifiés directement​ Vérifiez si un fichier de la bibliothèque a été modifié en dehors du gestionnaire de dépendances. La bibliothèque doit être gérée exclusivement via **npm** ou **yarn**, sans modification directe des fichiers installés. Les modifications manuelles peuvent produire des comportements anormaux difficiles à reproduire et empêchent toute assistance de la part du support Unico.L'utilisateur est **redirigé vers un lien hébergé par Unico**, où se déroule le parcours. Une fois celui-ci terminé, il est renvoyé vers l'URL définie lors de la création du processus (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 parcours n'a pas besoin de se dérouler à l'intérieur de la propre page de l'application. En revanche, faire sortir l'utilisateur de l'environnement du client tend à générer 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 parcours hébergé par Unico. Il existe deux façons courantes d'y diriger l'utilisateur : **Redirection standard.** L'utilisateur est redirigé directement vers l'URL du parcours. Une fois celui-ci terminé, Unico le redirige vers le `callbackUri` défini lors de la création du processus. **Nouvel onglet avec `window.open()`.** Le parcours s'ouvre dans un nouvel onglet du navigateur, ce qui maintient l'utilisateur dans un contexte distinct. Dans ce cas, il est recommandé de surveiller le changement d'URL vers le `callbackUri` et de fermer l'onglet une fois le processus terminé. Consultez la [documentation MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) pour plus de détails sur l'API. Dans les applications mobiles, il est courant d'utiliser une **WebView** pour ouvrir le parcours directement, sans redirection supplémentaire. Dans ce cas, le `callbackUri` accepte également un **deeplink**, ce qui permet à l'achèvement du parcours 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 d'acheminer l'utilisateur au bon endroit. Cette approche par WebView convient aux applications qui en intègrent déjà une ; une application entièrement native devrait préférer le SDK de la plateforme. #### Ne gardez pas les DevTools ouverts pendant les tests de capture​ Unico utilise plusieurs mécanismes pour sécuriser ses parcours, dont l'un détecte les DevTools ouverts comme un possible signal de fraude et bloque la soumission. Fermez les DevTools avant d'exécuter des tests de capture de bout en bout. Intégrations non prises en chargeLes modèles décrits dans cette documentation (accès direct et SDK de Parcours) sont les seules approches d'intégration officiellement prises en charge par Unico. Les intégrations qui s'écartent de ces standards peuvent provoquer des comportements inattendus, des défaillances du flux de sécurité et des interruptions du parcours, et ne seront pas couvertes par le support Unico.Quelques exemples d'approches non prises en charge : **Intégrer le SDK dans une WebView** dans les applications mobiles. Dans ces cas, la bonne approche consiste à utiliser le modèle **accès direct**, en ouvrant le lien du parcours directement dans la WebView, sans faire intervenir le SDK de Parcours. **Charger l'iFrame directement via une balise HTML `