--- 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/dual-api/developers/sdks-and-tools/web/web-integration/ locale: fr generated_by: markdown-export --- 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. :::tip[Choisir votre approche d'intégration] - **Web SDK** (paquet `unico-webframe`) : à utiliser lorsque votre back-end contrôle déjà le flux de vérification d'identité et n'a besoin que du composant de capture côté client. Il renvoie `base64` + JWT chiffré directement à votre callback ; vous gérez les appels à l'API. - **Web App Integration** (paquet `idpay-b2b-sdk`) : à utiliser lorsque vous souhaitez qu'Unico orchestre l'intégralité du parcours (flux multi-étapes, capture de document + Détection de Vie). Le paquet `idpay-b2b-sdk` alimente le modèle **SDK de Parcours** (iFrame) intégré ; le modèle **Accès direct** (redirection) ne nécessite aucune bibliothèque. ::: ## 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èle | Idéal pour | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Accès direct** | Applications mobiles qui utilisent déjà une WebView, ou flux web où le parcours peut se dérouler en dehors de la page principale | | **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 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### SDK de Parcours Le 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** : Installation** Le paquet `idpay-b2b-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. ```bash npm install idpay-b2b-sdk ``` 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. :::tip[Maintenez le SDK à jour] Rester 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ètre | Requis | Description | | --------- | ------ | --------------------------------------------------------------- | | `token` | Oui | Jeton du processus renvoyé par l'API Create Process | | `env` | Non | Définir sur `'uat'` uniquement pour les environnements de test | ```javascript import { ByUnicoSDK } from 'idpay-b2b-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ètre | Requis | Description | | -------------------------- | ------ | --------------------------------------------------------------- | | `transactionId` | Oui | ID du processus renvoyé par l'API Create Process | | `token` | Oui | Jeton du processus renvoyé par l'API Create Process | | `onFinish` | Oui | Callback exécuté lorsque le parcours 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 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. :::warning Le 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é : | Champ | Type | Description | | ------------------------- | ------------------- | -------------------------------------------------------------------------------------------- | | `type` | string | Comment le parcours s'est terminé : `'FINISH'` (terminé) ou `'CLOSE'` (l'utilisateur a fermé avant la fin) | | `transaction` | object \| undefined | Présent lorsque `type` vaut `'FINISH'` ; `undefined` lorsque `type` vaut `'CLOSE'` | | `transaction.id` | string | Identifiant du processus (le même `transactionId` fourni) | | `transaction.redirectUrl` | string | URL vers laquelle rediriger l'utilisateur après le parcours | La 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. ```javascript 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 : ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Applications exemples | Langage / Framework | Description | Dépôt | | --------------------- | ------------ | ---------- | | Angular | PoC en Angular qui implémente le Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC en JS Vanilla qui implémente le Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC en React qui implémente le Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC en Vue JS qui implémente le Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Sécurité :::note[Portée de cette section] Cette justification de sécurité s'applique spécifiquement à la **Web App Integration** (`idpay-b2b-sdk`). Le **Web SDK** (`unico-webframe`) utilise un modèle différent : il s'exécute entièrement dans le contexte de la page et [nécessite bien une CSP](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). Ce sont deux produits distincts avec des architectures de sécurité différentes. ::: 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. #### Ne gardez pas les DevTools ouverts pendant les tests de capture L'application Unico utilise le Capture SDK (unico-webframe) pour la capture faciale, qui 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. :::warning[Intégrations non prises en charge] Les 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 `