SDK d'intégration

Aperçu

Le SDK d’intégration Komerza vous permet d’intégrer de manière transparente notre expérience de paiement directement dans votre site web. Au lieu de rediriger les clients vers une page de paiement séparée, l’intégration crée une superposition modale qui garde les utilisateurs sur votre site tout en offrant un flux de paiement sécurisé et optimisé.

Démo en direct

Voir le SDK d’intégration en action avec notre démo interactive

Intégrez également notre script d’analyse pour récupérer les analyses de visiteurs sur votre site personnalisé pour des informations complètes sur le parcours client.

Fonctionnalités

Intégration transparente

La superposition modale garde les clients sur votre site pendant le paiement

Léger

Bundle JavaScript minimal sans dépendances externes

Support des thèmes

Thèmes clair, sombre et automatique pour correspondre au design de votre site

Compatible CSP

Support complet de la politique de sécurité du contenu avec intégration de nonce

Démarrage rapide

Ajoutez le script suivant dans le <head> de votre site web ou avant la balise fermante </body> :

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>

Méthode 1 : Attributs de données (recommandé pour les cas simples)

La façon la plus facile d’ajouter des boutons de paiement à votre site. Ajoutez simplement des attributs de données à n’importe quel bouton ou élément :

<button
  data-kmrza-product-id="YOUR_PRODUCT_ID"
  data-kmrza-variant-id="YOUR_VARIANT_ID"
  data-kmrza-quantity="1"
  data-kmrza-theme="auto"
>
  Acheter maintenant
</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  // Initialiser l'intégration pour lier tous les boutons avec des attributs de données
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Référence des attributs de données

Attribut	Requis	Description	Exemple
`data-kmrza-product-id`	✅ Oui	L’ID du produit Komerza	`"0f6294be-25d6-4ced-96df-7d500608c54d"`
`data-kmrza-variant-id`	✅ Oui	L’ID de la variante Komerza	`"96f846e5-5f22-46a2-97b3-a1c88f685577"`
`data-kmrza-quantity`	❌ Non	Quantité à acheter (défaut : 1)	`"2"`
`data-kmrza-theme`	❌ Non	Mode thème : `light`, `dark` ou `auto` (défaut : `auto`)	`"dark"`
`data-kmrza-return-url`	❌ Non	URL personnalisée vers laquelle rediriger après le paiement	`"https://example.com/merci"`
`data-kmrza-email`	❌ Non	Préremplir l’adresse e-mail du client	`"client@example.com"`
`data-kmrza-coupon-code`	❌ Non	Préremplir et appliquer automatiquement un code de coupon	`"SAVE20"`
`data-kmrza-metadata`	❌ Non	Chaîne JSON de métadonnées clé-valeur personnalisées	`"{"campaign":"summer"}"`

Méthode 2 : API JavaScript (pour les cas d’utilisation avancés)

Pour plus de contrôle, utilisez l’API JavaScript pour ouvrir le paiement par programmation :

<button id="checkout-btn">Acheter maintenant</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  document.getElementById("checkout-btn").addEventListener("click", () => {
    Komerza.open({
      items: [
        {
          productId: "YOUR_PRODUCT_ID",
          variantId: "YOUR_VARIANT_ID",
          quantity: 1,
        },
      ],
      theme: "auto", // 'light', 'dark', ou 'auto'
    });
  });
</script>

Articles multiples

Vous pouvez ajouter plusieurs produits au paiement à la fois :

Komerza.open({
  items: [
    {
      productId: "0f6294be-25d6-4ced-96df-7d500608c54d",
      variantId: "96f846e5-5f22-46a2-97b3-a1c88f685577",
      quantity: 2,
    },
    {
      productId: "54d6adb4-c160-4f73-b9c0-6c16970fff41",
      variantId: "37e70705-c603-4ab2-8a2e-d16e80288c8c",
      quantity: 1,
    },
  ],
  theme: "light",
});

Guide d’implémentation complet

Configuration HTML

Voici un exemple de page HTML complète :

<!DOCTYPE html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Ma Boutique</title>

    <!-- En-tête CSP (recommandé) -->
    <meta
      http-equiv="Content-Security-Policy"
      content="frame-src https://checkout.komerza.com; script-src 'self' 'nonce-abc123' https://checkout.komerza.com;"
    />
  </head>
  <body>
    <div class="product-container">
      <h1>Produit incroyable</h1>
      <p>Prix : 29,99 €</p>

      <!-- Votre bouton d'achat -->
      <button id="buy-now" class="buy-button">Acheter maintenant</button>
    </div>

    <!-- SDK d'intégration Komerza -->
    <script
      src="https://checkout.komerza.com/embed/embed.iife.js"
      nonce="abc123"
    ></script>

    <script nonce="abc123">
      // Votre code d'intégration ici
    </script>
  </body>
</html>

Intégration JavaScript

Intégration de base
Intégration avancée
Intégration React

// Initialiser au chargement de la page
document.addEventListener('DOMContentLoaded', function() {
  KomerzaEmbed.init();
  
  // Lier à votre bouton d'achat
  document.getElementById('buy-now').addEventListener('click', function() {
    KomerzaEmbed.open({
      items: [
        {
          productId: 'prod_123',
          variantId: 'var_456',
          quantity: 1
        }
      ]
    });
  });
});

// Intégration avancée avec gestion des erreurs et plusieurs produits
class CheckoutManager {
  constructor() {
    this.isInitialized = false;
    this.init();
  }
  
  init() {
    // Initialiser avec nonce CSP
    KomerzaEmbed.init({
      nonce: this.getCSPNonce()
    });
    
    this.isInitialized = true;
    this.bindEvents();
  }
  
  bindEvents() {
    // Lier à tous les boutons d'achat
    document.querySelectorAll('[data-buy-button]').forEach(button => {
      button.addEventListener('click', (e) => {
        e.preventDefault();
        this.handlePurchase(button);
      });
    });
    
    // Optionnel : Lier aux événements de fermeture
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') {
        KomerzaEmbed.close();
      }
    });
  }
  
  handlePurchase(button) {
    const productId = button.dataset.productId;
    const variantId = button.dataset.variantId;
    const quantity = parseInt(button.dataset.quantity) || 1;
    
    if (!productId || !variantId) {
      console.error('ID produit ou variante manquant');
      return;
    }
    
    try {
      KomerzaEmbed.open({
        items: [{
          productId,
          variantId,
          quantity
        }],
        theme: this.getTheme()
      });
    } catch (error) {
      console.error('Échec de l\'ouverture du paiement :', error);
      // Retour à l'URL de paiement directe
      this.fallbackCheckout(productId, variantId, quantity);
    }
  }
  
  getTheme() {
    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
      return 'dark';
    }
    return 'light';
  }
  
  getCSPNonce() {
    const script = document.querySelector('script[nonce]');
    return script ? script.getAttribute('nonce') : null;
  }
  
  fallbackCheckout(productId, variantId, quantity) {
    const checkoutUrl = `https://checkout.komerza.com/product/${productId}/${variantId}?qty=${quantity}`;
    window.location.href = checkoutUrl;
  }
}

document.addEventListener('DOMContentLoaded', function() {
  new CheckoutManager();
});

import React, { useEffect, useState } from 'react';

const ProductPage: React.FC = () => {
  const [isEmbedReady, setIsEmbedReady] = useState(false);
  
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://checkout.komerza.com/embed/embed.iife.js';
    script.onload = () => {
      window.KomerzaEmbed.init();
      setIsEmbedReady(true);
    };
    document.head.appendChild(script);
    
    return () => {
      document.head.removeChild(script);
    };
  }, []);
  
  const handleBuyClick = () => {
    if (!isEmbedReady) {
      console.warn('SDK d\'intégration pas encore prêt');
      return;
    }
    
    window.KomerzaEmbed.open({
      items: [
        {
          productId: 'prod_123',
          variantId: 'var_456',
          quantity: 1
        }
      ],
      theme: 'auto'
    });
  };
  
  return (
    <div className="product-page">
      <h1>Produit incroyable</h1>
      <p>Prix : 29,99 €</p>
      <button 
        onClick={handleBuyClick}
        disabled={!isEmbedReady}
        className="buy-button"
      >
        {isEmbedReady ? 'Acheter maintenant' : 'Chargement...'}
      </button>
    </div>
  );
};

export default ProductPage;

Référence API

`Komerza.init(options?)`

Initialise l’intégration et lie automatiquement tous les éléments avec des attributs data-kmrza-*.

Komerza.init({
  nonce: "VOTRE_NONCE_CSP", // Optionnel : pour la politique de sécurité du contenu
});

Options :

nonce (optionnel) : Nonce CSP pour les styles et scripts injectés

Remarque : Ceci est appelé automatiquement lors de l’utilisation de l’API JS (Komerza.open()), mais doit être appelé explicitement si vous utilisez des attributs de données.

`Komerza.open(options)`

Ouvre la modale de paiement par programmation.

Komerza.open({
  items: [
    {
      productId: string,    // Requis
      variantId: string,    // Requis
      quantity?: number     // Optionnel, défaut : 1
    }
  ],
  theme?: 'light' | 'dark' | 'auto',  // Optionnel, défaut : 'auto'
  affiliateCode?: string,   // Optionnel, remplacer le code de suivi d'affiliation
  returnUrl?: string,       // Optionnel, URL de retour personnalisée après paiement
  email?: string,           // Optionnel, préremplir l'e-mail client
  couponCode?: string,      // Optionnel, préremplir et appliquer un code coupon
  metadata?: Record<string, string>  // Optionnel, métadonnées personnalisées de commande
});

`Komerza.close()`

Ferme la modale de paiement par programmation.

Komerza.close();

Bouton de base

<button
  data-kmrza-product-id="0f6294be-25d6-4ced-96df-7d500608c54d"
  data-kmrza-variant-id="96f846e5-5f22-46a2-97b3-a1c88f685577"
>
  Ajouter au panier
</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Thème sombre avec quantité personnalisée

<button
  data-kmrza-product-id="0f6294be-25d6-4ced-96df-7d500608c54d"
  data-kmrza-variant-id="96f846e5-5f22-46a2-97b3-a1c88f685577"
  data-kmrza-quantity="3"
  data-kmrza-theme="dark"
  class="buy-button"
>
  Acheter 3 maintenant
</button>

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Intégration Next.js

// components/CheckoutButton.jsx
"use client";

import { useEffect } from "react";
import Script from "next/script";

export default function CheckoutButton({ productId, variantId, quantity = 1 }) {
  const handleClick = () => {
    if (window.Komerza) {
      window.Komerza.open({
        items: [{ productId, variantId, quantity }],
      });
    }
  };

  return (
    <>
      <Script
        src="https://checkout.komerza.com/embed/embed.iife.js"
        strategy="lazyOnload"
      />
      <button onClick={handleClick}>Acheter maintenant</button>
    </>
  );
}

Dépannage

Le paiement ne s’ouvre pas

Assurez-vous que le script est chargé (l’attribut defer est recommandé)
Vérifiez les erreurs dans la console du navigateur
Vérifiez que vos IDs produit et variante sont corrects
Si vous utilisez des attributs de données, assurez-vous que Komerza.init() est appelé après le chargement du DOM

La modale apparaît derrière d’autres éléments

La modale utilise un z-index élevé (9999). Si elle est toujours derrière des éléments, vérifiez vos CSS pour des valeurs z-index concurrentes.

Le thème ne s’applique pas

Le paramètre theme accepte uniquement 'light', 'dark' ou 'auto'. Vérifiez les fautes de frappe.

Affiliés

Le SDK d’intégration Komerza prend en charge le suivi d’affiliation prêt à l’emploi :

Par défaut, l’intégration supportera automatiquement le deep linking en utilisant le paramètre de requête ?ref sur n’importe quelle URL où il s’exécute.
Le SDK lira également le cookie kmrza_affiliate (s’il est présent) et transmettra ce code d’affiliation à la commande automatiquement.
Vous pouvez remplacer le comportement automatique en passant un affiliateCode explicite à KomerzaEmbed.open().

Politique de sécurité du contenu (CSP)

Pour une sécurité renforcée, configurez vos en-têtes CSP pour autoriser l’intégration Komerza :

Content-Security-Policy:
  frame-src https://checkout.komerza.com;
  script-src 'self' 'nonce-VOTRE_NONCE' https://checkout.komerza.com;
  style-src 'self' 'nonce-VOTRE_NONCE';

Puis passez le nonce au SDK :

KomerzaEmbed.init({
  nonce: "VOTRE_NONCE",
});

Meilleures pratiques

Performance

Charger le script SDK de manière asynchrone lorsque c’est possible
Initialiser le SDK tôt mais n’ouvrir les modales qu’à l’interaction de l’utilisateur
Implémenter des états de chargement appropriés pour les boutons d’achat

Expérience utilisateur

Fournir des indicateurs de chargement clairs - Gérer les pannes réseau gracieusement avec des URL de secours - Supporter la navigation au clavier (Échap pour fermer)

Sécurité

Toujours utiliser les en-têtes CSP en production
Valider les IDs produit et variante avant d’ouvrir le paiement
Ne jamais exposer de données sensibles dans le code côté client

Intégration des analyses

Intégrez également notre script d’analyse pour récupérer les analyses de visiteurs sur votre site personnalisé

Support

Besoin d’aide pour l’intégration ?

Page de démo

Démo interactive avec exemples de code source

Support développeur

Obtenez un support technique pour les problèmes d’intégration

Démarrer

Configuration du Magasin

Guides d'Intégration

Configuration des Paiements

Aperçu

Démo en direct

Fonctionnalités

Intégration transparente

Léger

Support des thèmes

Compatible CSP

Démarrage rapide

Méthode 1 : Attributs de données (recommandé pour les cas simples)

Référence des attributs de données

Méthode 2 : API JavaScript (pour les cas d’utilisation avancés)

Articles multiples

Guide d’implémentation complet

Configuration HTML

Intégration JavaScript

Référence API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Bouton de base

Thème sombre avec quantité personnalisée

Intégration Next.js

Dépannage

Le paiement ne s’ouvre pas

La modale apparaît derrière d’autres éléments

Le thème ne s’applique pas

Affiliés

Politique de sécurité du contenu (CSP)

Meilleures pratiques

Intégration des analyses

Intégration des analyses

Support

Page de démo

Support développeur

Démarrer

Configuration du Magasin

Guides d'Intégration

Configuration des Paiements

​Aperçu

Démo en direct

​Fonctionnalités

Intégration transparente

Léger

Support des thèmes

Compatible CSP

​Démarrage rapide

​Méthode 1 : Attributs de données (recommandé pour les cas simples)

​Référence des attributs de données

​Méthode 2 : API JavaScript (pour les cas d’utilisation avancés)

​Articles multiples

​Guide d’implémentation complet

​Configuration HTML

​Intégration JavaScript

​Référence API

​Komerza.init(options?)

​Komerza.open(options)

​Komerza.close()

​Bouton de base

​Thème sombre avec quantité personnalisée

​Intégration Next.js

​Dépannage

​Le paiement ne s’ouvre pas

​La modale apparaît derrière d’autres éléments

​Le thème ne s’applique pas

​Affiliés

​Politique de sécurité du contenu (CSP)

​Meilleures pratiques

​Intégration des analyses

Intégration des analyses

​Support

Page de démo

Support développeur

Aperçu

Fonctionnalités

Démarrage rapide

Méthode 1 : Attributs de données (recommandé pour les cas simples)

Référence des attributs de données

Méthode 2 : API JavaScript (pour les cas d’utilisation avancés)

Articles multiples

Guide d’implémentation complet

Configuration HTML

Intégration JavaScript

Référence API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Bouton de base

Thème sombre avec quantité personnalisée

Intégration Next.js

Dépannage

Le paiement ne s’ouvre pas

La modale apparaît derrière d’autres éléments

Le thème ne s’applique pas

Affiliés

Politique de sécurité du contenu (CSP)

Meilleures pratiques

Intégration des analyses

Support