Full SDK (Web)

👍

SDK recommandé

Nous recommandons d'utiliser le Seamless Web SDK pour une expérience d'intégration fluide. Cette option offre une solution de paiement flexible avec des composants d'interface utilisateur (UI) pré-intégrés et des options de personnalisation.

Bienvenue dans le guide du Full Web SDK de Yuno. Ce guide vous aidera à démarrer avec les solutions de paiement de Yuno. Que vous cherchiez à implémenter votre première intégration de paiement ou à améliorer votre configuration existante, ce guide fournit toutes les informations nécessaires pour créer une expérience de paiement transparente pour vos utilisateurs.

📘

Documentation de la dernière version

Ce guide couvre la dernière version de notre Full Web SDK. Pour en savoir plus sur les versions précédentes, consultez les liens connexes ou rendez-vous sur le journal des modifications.

Choisissez votre méthode d'intégration

Nous vous aidons à choisir la méthode d'intégration qui correspond le mieux à vos besoins. Chaque approche présente des avantages spécifiques, et la sélection de la bonne méthode dépend de votre environnement de développement, de vos exigences techniques et de vos préférences.

• Méthode 1 (HTML): Ajoutez une seule balise de script à votre fichier HTML. Il s'agit de la méthode la plus simple, idéale pour les implémentations de base et les prototypes rapides.
• Méthode 2 (JavaScript dynamique): Chargez le SDK par programmation avec gestion des erreurs et états de chargement personnalisés. Cette méthode est idéale pour les applications nécessitant plus de contrôle sur l'intégration.
• Méthode 3 (NPM): Utilisez notre package NPM dans les applications JavaScript modernes. C'est l'approche que nous recommandons, avec la gestion des dépendances, le tree-shaking et la prise en charge de TypeScript.

1. Ajouter le script SDK directement en HTML

La manière la plus simple d'intégrer le SDK Yuno est d'ajouter une balise <script> à votre fichier HTML. Cette méthode offre une implémentation rapide tout en assurant un chargement asynchrone correct. Le SDK expose un événement qui signale quand il est complètement chargé, vous permettant d'initialiser et d'utiliser ses fonctionnalités en toute sécurité au bon moment.

📘

Important

Bien que l'attribut defer garantisse que le script est exécuté après l'analyse du HTML, il ne garantit pas que le script SDK se chargera toujours en dernier. Dans certains cas, si le SDK se charge plus rapidement que prévu et que l'écouteur d'événement est déclaré après, l'événement yuno-sdk-ready peut avoir déjà été déclenché — et votre écouteur ne le capturera pas. Pour éviter cela, définissez toujours l'écouteur avant de charger le script SDK.

Commencez par configurer l'écouteur d'événement, puis chargez le SDK :

<script>
  window.addEventListener('yuno-sdk-ready', () => {
    console.log('SDK loaded');
    const yuno = await Yuno.initialize(PUBLIC_API_KEY);
  });
</script>

<script defer src="https://sdk-web.y.uno/v1.5/main.js"></script>

2. Injecter le SDK dynamiquement à l'aide de JavaScript

La méthode d'injection JavaScript dynamique offre un contrôle accru sur le chargement et l'initialisation du SDK. Cette approche vous permet de :

• Charger le SDK par programmation lorsque cela est nécessaire
• Implémenter des états de chargement et une gestion des erreurs personnalisés
• Contrôler précisément le moment où le SDK devient disponible
• Synchroniser l'initialisation du SDK avec la logique de votre application
• Créer une gestion des erreurs sur mesure pour votre cas d'utilisation

Cette méthode est idéale lorsque vous avez besoin d'un contrôle granulaire sur le processus de chargement du SDK et que vous souhaitez gérer divers scénarios avec précision.

Créez une fonction pour injecter le SDK dynamiquement :

export const injectScript = async (): Promise<boolean> => {
  const head = document.getElementsByTagName('head')[0];
  const js = document.createElement('script');
  js.src = "https://sdk-web.y.uno/v1.5/main.js";
  js.defer = true;

  return new Promise((resolve, reject) => {
    window.addEventListener('yuno-sdk-ready', () => {
      resolve(true);
    });

    js.onerror = (error) => {
      const event = new CustomEvent('yuno-sdk-error', { detail: error });
      window.dispatchEvent(event);
      reject(new Error(`Failed to load script: ${js.src} - ${error.message}`));
    };

    head.appendChild(js);
  });
};

Utilisez la fonction pour injecter le SDK :

await injectScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

3. Utiliser le module NPM

Pour les projets utilisant la gestion de packages NPM, vous pouvez installer le SDK en tant que module via NPM. Cette approche offre une meilleure gestion des dépendances, un meilleur contrôle de version et une intégration transparente avec les outils et frameworks de construction JavaScript modernes. Elle est particulièrement bénéfique pour les applications utilisant des bundlers comme webpack, Rollup ou Vite.

npm install @yuno-payments/sdk-web

Ensuite, chargez et initialisez le SDK comme suit :

import { loadScript } from '@yuno-payments/sdk-web';

const yuno = await loadScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Améliorer les performances grâce à preconnect

Pour optimiser les performances et réduire la latence, nous recommandons d'ajouter des liens preconnect le plus tôt possible dans la balise <head> de votre document HTML. Ces liens permettent aux navigateurs de se connecter rapidement à nos serveurs avant que les ressources ne soient réellement demandées. Cette approche proactive peut améliorer considérablement les temps de chargement, en particulier pour la configuration initiale du SDK et les appels d'API ultérieurs.

<link rel="preconnect" href="https://sdk-web.y.uno" />
<link rel="preconnect" href="https://api.y.uno" />
<link rel="preconnect" href="https://sdk-web-card.prod.y.uno" />

Implémentation du Full SDK

Après avoir intégré le SDK à l'aide de l'une des méthodes décrites ci-dessus, suivez ces étapes pour implémenter la fonctionnalité complète de paiement :

Restez informé

Visitez le journal des modifications pour les dernières mises à jour du SDK et l'historique des versions.