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.

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 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.

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.

  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.

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

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.

avertissement

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.

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 :

Sécurité

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. 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.

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 <iframe>, sans passer par le SDK de Parcours. L'iFrame est un détail d'implémentation interne du SDK et ne doit pas être instancié manuellement. La bonne approche consiste à utiliser le SDK de Parcours, qui gère le cycle de vie de l'iFrame de manière sécurisée et conforme aux standards attendus.

En cas de doute sur la conformité d'une approche au standard pris en charge, consultez la documentation ou contactez le support avant de poursuivre l'implémentation.