Intégration d'application Web

Cette page couvre les deux approches d'intégration côté client pour le contrat Web & SDK : rediriger l'utilisateur vers un parcours hébergé par Unico, et intégrer le parcours via le SDK iFrame.

Redirection de l'utilisateur

Après la création d'un processus, la réponse inclut une URL pointant vers le parcours hébergé par Unico. Utilisez cette URL pour transférer l'utilisateur vers l'expérience de capture. Il existe deux façons de gérer cette transition :

1. Redirection standard

Redirigez l'utilisateur directement vers l'URL du parcours. Lorsque l'utilisateur termine le processus, Unico le redirige vers l'URL que vous avez spécifiée lors de la création du processus.

2. Nouvel onglet avec window.open()

Ouvrez le parcours dans un nouvel onglet du navigateur afin que l'utilisateur reste dans un contexte séparé. Surveillez le changement d'URL vers votre URL de retour et fermez l'onglet lorsque le processus est terminé.

Pour plus de détails sur l'API window.open(), consultez la documentation MDN.

iFrame

avertissement

Les intégrations qui ne respectent pas les normes de cette documentation peuvent provoquer des interruptions inattendues et ne seront pas couvertes par le support Unico.

Exemples d'approches non prises en charge : intégrer le SDK dans une WebView, ou charger l'iFrame directement via une balise HTML.

Comment démarrer

Étape 1 — Installation

Le SDK by Unico utilise le même package qu'IDPay :

npm install idpay-b2b-sdk

conseil

Installez sans épingler une version spécifique afin que votre gestionnaire de packages récupère toujours automatiquement les dernières versions mineures et de correctifs.

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 ressources, créant une expérience plus fluide pour l'utilisateur final. Appelez cette méthode le plus tôt possible dans votre flux.

Paramètre	Requis	Description
type	Oui	Définissez sur 'IFRAME' pour les flux by Unico
token	Oui	Jeton de processus renvoyé par l'API de création de processus
env	Non	Définissez sur 'uat' uniquement pour les environnements de test

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

Étape 3 — Appeler open(options)

Affiche l'iFrame pré-chargé et démarre le flux de messages entre votre page et le parcours Unico.

Paramètre	Requis	Description
transactionId	Oui	ID de processus renvoyé par l'API de création de processus
token	Oui	Jeton de processus renvoyé par l'API de création de processus
onFinish	Oui	Callback exécuté lorsque le parcours se termine ou est fermé

Le callback onFinish reçoit un objet de processus avec l'ID de transaction, une URL de redirection et le type de completion.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

Le diagramme de séquence ci-dessous illustre comment utiliser le SDK et le résultat de l'API pour configurer l'iFrame :

Sécurité

Opter pour la solution iFrame avec jeton d'authentification plutôt que CSP

Après une analyse approfondie, l'approche choisie utilise des iframes avec des jetons d'authentification plutôt que d'implémenter une Content Security Policy (CSP). Cette décision a été motivée par les exigences de sécurité et la flexibilité nécessaire pour répondre aux besoins des clients.

Contexte et défis avec CSP

Content Security Policy est un outil puissant pour protéger les applications web contre les attaques XSS et d'injection de code. Cependant, configurer une politique CSP nécessite de définir une liste stricte de domaines de confiance. Cette approche est efficace lorsque les domaines sont fixes et prévisibles — mais pour les clients qui utilisent des domaines dynamiques et variables, cette configuration rigide présente des défis importants.

Vulnérabilité avec les domaines dynamiques

Les domaines dynamiques représentent un risque de sécurité substantiel lors de l'utilisation de CSP. Lorsqu'un client possède des domaines qui changent fréquemment ou qui sont créés dynamiquement, la politique CSP doit être constamment mise à jour pour inclure les nouveaux domaines. Cela augmente non seulement la charge de maintenance, mais expose également chaque domaine répertorié dans la politique comme une surface d'attaque potentielle s'il n'est pas géré de manière adéquate.

Solution avec iFrame et jeton d'authentification

Pour atténuer ces risques et répondre à la flexibilité requise par les clients, la solution choisie combine les iframes avec des jetons d'authentification, offrant une couche de sécurité supplémentaire sans nécessiter une liste de domaines statiques.

Fonctionnement :

• Authentification sécurisée — chaque iFrame est chargé avec un jeton d'authentification unique par transaction, garantissant que seuls les utilisateurs autorisés peuvent accéder au contenu. Le jeton est vérifié en temps réel.
• Isolation du contenu — l'iFrame s'exécute dans un contexte de navigation séparé, réduisant le risque d'interférence entre différentes origines et atténuant les attaques potentielles.
• Flexibilité pour les domaines dynamiques — en ne s'appuyant pas sur une politique CSP statique, la solution s'adapte aux domaines clients dynamiques sans nécessiter de mises à jour constantes de la politique.