--- 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/human-token/integrations/web/web-integration/ locale: fr generated_by: markdown-export --- 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 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 `callbackUri` dé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 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 les 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 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. ```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 ``` ### Journeys SDK 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. ```bash 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. :::tip[Maintenir le SDK à jour] 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"); ``` :::info 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 | ```javascript 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. :::warning 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é. ```javascript 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 : ```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 d'exemple | Langage / Framework | Description | Dépôt | | --------------------- | ------------ | ---------- | | Angular | PoC en Angular implémentant le Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC en JS Vanilla implémentant le Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC en React implémentant le Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC en Vue JS implémentant le Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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. :::warning[Intégrations non supportées] 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 `