Embed SDK

Übersicht

Das Komerza Embed SDK ermöglicht es dir, unsere Checkout-Erfahrung nahtlos direkt in deine Website zu integrieren. Anstatt Kunden auf eine separate Checkout-Seite weiterzuleiten, erstellt das Embed eine modale Überlagerung, die Nutzer auf deiner Website behält und gleichzeitig einen sicheren, optimierten Zahlungsablauf bietet.

Live-Demo

Sieh das Embed SDK in Aktion mit unserer interaktiven Demo

Integriere auch unser Analytics-Skript, um Besucheranalysen auf deiner benutzerdefinierten Website für vollständige Einblicke in die Customer Journey zurückzubringen.

Funktionen

Nahtlose Integration

Modale Überlagerung hält Kunden während des Checkouts auf deiner Website

Leichtgewichtig

Minimales JavaScript-Bundle ohne externe Abhängigkeiten

Theme-Unterstützung

Helle, dunkle und automatische Themes passend zum Design deiner Website

CSP-kompatibel

Vollständige Content Security Policy-Unterstützung mit Nonce-Integration

Schnellstart

Füge das folgende Skript in das <head> deiner Website oder vor dem schließenden </body>-Tag ein:

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

Methode 1: Datenattribute (Empfohlen für einfache Anwendungsfälle)

Die einfachste Möglichkeit, Checkout-Buttons zu deiner Website hinzuzufügen. Füge einfach Datenattribute zu einem beliebigen Button oder Element hinzu:

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

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  // Embed initialisieren, um alle Buttons mit Datenattributen zu verknüpfen
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Datenattribute-Referenz

Attribut	Erforderlich	Beschreibung	Beispiel
`data-kmrza-product-id`	✅ Ja	Die Produkt-ID aus Komerza	`"0f6294be-25d6-4ced-96df-7d500608c54d"`
`data-kmrza-variant-id`	✅ Ja	Die Varianten-ID aus Komerza	`"96f846e5-5f22-46a2-97b3-a1c88f685577"`
`data-kmrza-quantity`	❌ Nein	Zu kaufende Menge (Standard: 1)	`"2"`
`data-kmrza-theme`	❌ Nein	Theme-Modus: `light`, `dark` oder `auto` (Standard: `auto`)	`"dark"`
`data-kmrza-return-url`	❌ Nein	Benutzerdefinierte URL zur Weiterleitung nach der Zahlung	`"https://example.com/danke"`
`data-kmrza-email`	❌ Nein	E-Mail-Adresse des Kunden vorausfüllen	`"kunde@example.com"`
`data-kmrza-coupon-code`	❌ Nein	Couponcode vorausfüllen und automatisch anwenden	`"SAVE20"`
`data-kmrza-metadata`	❌ Nein	JSON-String mit benutzerdefinierten Schlüssel-Wert-Metadaten	`"{"campaign":"summer"}"`

Methode 2: JavaScript-API (Für fortgeschrittene Anwendungsfälle)

Für mehr Kontrolle nutze die JavaScript-API, um den Checkout programmgesteuert zu öffnen:

<button id="checkout-btn">Jetzt kaufen</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' oder 'auto'
    });
  });
</script>

Mehrere Artikel

Du kannst mehrere Produkte gleichzeitig zum Checkout hinzufügen:

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",
});

Vollständiger Implementierungsleitfaden

HTML-Setup

Hier ist ein vollständiges HTML-Seitenbeispiel:

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

    <!-- CSP-Header (empfohlen) -->
    <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>Tolles Produkt</h1>
      <p>Preis: 29,99 €</p>

      <!-- Dein Kaufen-Button -->
      <button id="buy-now" class="buy-button">Jetzt kaufen</button>
    </div>

    <!-- Komerza Embed SDK -->
    <script
      src="https://checkout.komerza.com/embed/embed.iife.js"
      nonce="abc123"
    ></script>

    <script nonce="abc123">
      // Dein Integrationscode hier
    </script>
  </body>
</html>

JavaScript-Integration

Basis-Integration
Erweiterte Integration
React-Integration

document.addEventListener('DOMContentLoaded', function() {
  KomerzaEmbed.init();
  
  document.getElementById('buy-now').addEventListener('click', function() {
    KomerzaEmbed.open({
      items: [
        {
          productId: 'prod_123',
          variantId: 'var_456',
          quantity: 1
        }
      ]
    });
  });
});

class CheckoutManager {
  constructor() {
    this.isInitialized = false;
    this.init();
  }
  
  init() {
    KomerzaEmbed.init({
      nonce: this.getCSPNonce()
    });
    this.isInitialized = true;
    this.bindEvents();
  }
  
  bindEvents() {
    document.querySelectorAll('[data-buy-button]').forEach(button => {
      button.addEventListener('click', (e) => {
        e.preventDefault();
        this.handlePurchase(button);
      });
    });
    
    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('Produkt- oder Varianten-ID fehlt');
      return;
    }
    
    try {
      KomerzaEmbed.open({ items: [{ productId, variantId, quantity }], theme: this.getTheme() });
    } catch (error) {
      console.error('Checkout konnte nicht geöffnet werden:', error);
      this.fallbackCheckout(productId, variantId, quantity);
    }
  }
  
  getTheme() {
    return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
  }
  
  getCSPNonce() {
    return document.querySelector('script[nonce]')?.getAttribute('nonce') ?? null;
  }
  
  fallbackCheckout(productId, variantId, quantity) {
    window.location.href = `https://checkout.komerza.com/product/${productId}/${variantId}?qty=${quantity}`;
  }
}

document.addEventListener('DOMContentLoaded', () => 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) return;
    window.KomerzaEmbed.open({
      items: [{ productId: 'prod_123', variantId: 'var_456', quantity: 1 }],
      theme: 'auto'
    });
  };
  
  return (
    <div className="product-page">
      <h1>Tolles Produkt</h1>
      <p>Preis: 29,99 €</p>
      <button onClick={handleBuyClick} disabled={!isEmbedReady} className="buy-button">
        {isEmbedReady ? 'Jetzt kaufen' : 'Wird geladen...'}
      </button>
    </div>
  );
};

export default ProductPage;

API-Referenz

`Komerza.init(options?)`

Initialisiert das Embed und verknüpft automatisch alle Elemente mit data-kmrza-*-Attributen.

Komerza.init({
  nonce: "DEIN_CSP_NONCE", // Optional: für Content Security Policy
});

Hinweis: Dies wird automatisch aufgerufen, wenn die JS-API (Komerza.open()) verwendet wird, muss aber explizit aufgerufen werden, wenn Datenattribute verwendet werden.

`Komerza.open(options)`

Öffnet die Checkout-Modal programmgesteuert.

Komerza.open({
  items: [{ productId: string, variantId: string, quantity?: number }],
  theme?: 'light' | 'dark' | 'auto',
  affiliateCode?: string,
  returnUrl?: string,
  email?: string,
  couponCode?: string,
  metadata?: Record<string, string>
});

`Komerza.close()`

Schließt die Checkout-Modal programmgesteuert.

Komerza.close();

Next.js-Integration

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

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}>Jetzt kaufen</button>
    </>
  );
}

Fehlerbehebung

Der Checkout öffnet sich nicht

Stelle sicher, dass das Skript geladen ist (das defer-Attribut wird empfohlen)
Prüfe die Browserkonsole auf Fehler
Überprüfe, ob deine Produkt- und Varianten-IDs korrekt sind
Wenn du Datenattribute verwendest, stelle sicher, dass Komerza.init() nach dem DOM-Laden aufgerufen wird

Das Modal verwendet einen hohen z-index (9999). Wenn es noch hinter Elementen liegt, überprüfe dein CSS auf konkurrierende z-index-Werte.

Affiliates

Das Komerza Embed SDK unterstützt Affiliate-Tracking sofort einsatzbereit. Der ?ref-Abfrageparameter wird automatisch unterstützt, und der kmrza_affiliate-Cookie wird automatisch gelesen.

Content Security Policy (CSP)

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

KomerzaEmbed.init({ nonce: "DEIN_NONCE" });

Best Practices

Performance

SDK-Skript asynchron laden, wenn möglich
SDK früh initialisieren, aber Modals nur bei Benutzerinteraktion öffnen
Ordnungsgemäße Ladezustände für Kauf-Buttons implementieren

Benutzererfahrung

Klare Ladeindikatoren bereitstellen - Netzwerkfehler mit Fallback-URLs behandeln - Tastaturnavigation unterstützen (Esc zum Schließen)

Sicherheit

Immer CSP-Header in Produktion verwenden
Produkt- und Varianten-IDs vor dem Öffnen des Checkouts validieren
Niemals sensible Daten im clientseitigen Code offenlegen

Support

Brauchst du Hilfe bei der Integration?

Demo-Seite

Interaktive Demo mit Quellcode-Beispielen

Entwickler-Support

Technischen Support für Integrationsprobleme erhalten

Erste Schritte

Shop-Einrichtung

Integrationsleitfäden

Zahlungseinrichtung

Übersicht

Live-Demo

Funktionen

Nahtlose Integration

Leichtgewichtig

Theme-Unterstützung

CSP-kompatibel

Schnellstart

Methode 1: Datenattribute (Empfohlen für einfache Anwendungsfälle)

Datenattribute-Referenz

Methode 2: JavaScript-API (Für fortgeschrittene Anwendungsfälle)

Mehrere Artikel

Vollständiger Implementierungsleitfaden

HTML-Setup

JavaScript-Integration

API-Referenz

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Next.js-Integration

Fehlerbehebung

Der Checkout öffnet sich nicht

Affiliates

Content Security Policy (CSP)

Best Practices

Support

Demo-Seite

Entwickler-Support

Erste Schritte

Shop-Einrichtung

Integrationsleitfäden

Zahlungseinrichtung

​Übersicht

Live-Demo

​Funktionen

Nahtlose Integration

Leichtgewichtig

Theme-Unterstützung

CSP-kompatibel

​Schnellstart

​Methode 1: Datenattribute (Empfohlen für einfache Anwendungsfälle)

​Datenattribute-Referenz

​Methode 2: JavaScript-API (Für fortgeschrittene Anwendungsfälle)

​Mehrere Artikel

​Vollständiger Implementierungsleitfaden

​HTML-Setup

​JavaScript-Integration

​API-Referenz

​Komerza.init(options?)

​Komerza.open(options)

​Komerza.close()

​Next.js-Integration

​Fehlerbehebung

​Der Checkout öffnet sich nicht

​Modal erscheint hinter anderen Elementen

​Affiliates

​Content Security Policy (CSP)

​Best Practices

​Support

Demo-Seite

Entwickler-Support

Übersicht

Funktionen

Schnellstart

Methode 1: Datenattribute (Empfohlen für einfache Anwendungsfälle)

Datenattribute-Referenz

Methode 2: JavaScript-API (Für fortgeschrittene Anwendungsfälle)

Mehrere Artikel

Vollständiger Implementierungsleitfaden

HTML-Setup

JavaScript-Integration

API-Referenz

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Next.js-Integration

Fehlerbehebung

Der Checkout öffnet sich nicht

Modal erscheint hinter anderen Elementen

Affiliates

Content Security Policy (CSP)

Best Practices

Support