Zum Hauptinhalt springen
Komerza Embed SDK in Aktion Komerza Embed SDK in Aktion

Ü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:

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:

Datenattribute-Referenz

Kunden die Variante wählen lassen

data-kmrza-variant-id ist optional. Wenn Sie es weglassen, öffnet der Checkout mit einer Variantenauswahl, in der der Kunde vor dem Bezahlen seine Variante wählt.
Praktisch für einen einzelnen Kaufbutton bei Produkten mit mehreren Editionen, Stufen oder Laufzeiten. Geben Sie data-kmrza-variant-id an, wenn der Kunde direkt bei einer bestimmten Variante landen soll.

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

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

Mehrere Artikel

Du kannst mehrere Produkte gleichzeitig zum Checkout hinzufügen:

Vollständiger Implementierungsleitfaden

HTML-Setup

Hier ist ein vollständiges HTML-Seitenbeispiel:

JavaScript-Integration

API-Referenz

Komerza.init(options?)

Initialisiert das Embed und verknüpft automatisch alle Elemente mit data-kmrza-*-Attributen.
Dieser Abschnitt ist noch nicht übersetzt und wird vorerst auf Englisch angezeigt.
Options:
  • nonce (optional): CSP nonce for injected styles and scripts
  • preload (optional): Boot the checkout frame ahead of the click (default: true). See below.
Hinweis: Dies wird automatisch aufgerufen, wenn die JS-API (Komerza.open()) verwendet wird, muss aber explizit aufgerufen werden, wenn Datenattribute verwendet werden.

Preloading the checkout

By default the SDK boots the checkout frame hidden as soon as the first buy button with data-kmrza-* attributes scrolls into view. The frame loads the checkout shell, its JavaScript and the connection to the Komerza API while the customer is still reading, so when they click the only thing left to wait for is their basket. Without it, the frame is created on the press that precedes the click, which saves far less. What it costs: one hidden load of the checkout page (the page and its scripts) from checkout.komerza.com per page view with a visible buy button, whether or not anyone clicks. The checkout assets are cached at Cloudflare’s edge, so the load is cheap and does not touch your own server. Preloading is skipped automatically when the customer’s browser has data saver turned on, and it waits until the tab is actually visible, so a tab opened in the background pays nothing until it is brought to the front. The frame is the same iframe the modal uses, so your frame-src CSP rule already covers it. Turn it off by passing preload: false:
If you only paste the script tag and never call Komerza.init() yourself, set it on the tag instead:
Either form disables the boot frame; the SDK then falls back to warming the frame on the press before the click, as it always has.

Komerza.open(options)

Öffnet die Checkout-Modal programmgesteuert.

Komerza.close()

Schließt die Checkout-Modal programmgesteuert.

Komerza.preload()

Boots the checkout frame hidden, ahead of a click. This is what the SDK does on its own when a data-kmrza-* button scrolls into view (see Preloading the checkout), but if you open checkout only through Komerza.open() there are no bound buttons to watch, so nothing preloads unless you ask for it. Call it once your own buy button is on screen:
It is safe to call more than once: only one checkout frame is ever booted per page. The next Komerza.open() reuses the booted frame if it is still fresh and then only waits for the basket; a frame left idle for several minutes is discarded and checkout opens the usual way.

Next.js-Integration

Fehlerbehebung

Der Checkout öffnet sich nicht

  1. Stelle sicher, dass das Skript geladen ist (das defer-Attribut wird empfohlen)
  2. Prüfe die Browserkonsole auf Fehler
  3. Überprüfe, ob deine Produkt- und Varianten-IDs korrekt sind
  4. 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.

I see a request to checkout.komerza.com/embed on page load

That is the SDK preloading the checkout frame because a buy button is on screen - see Preloading the checkout. It is one hidden load of the checkout page per page view (the page and its scripts, served from Cloudflare’s cache), and no order or checkout session is created until the customer clicks. If you would rather it did not happen, pass preload: false to Komerza.init() or add data-kmrza-preload="false" to the script tag.

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)

Best Practices

  • 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
  • Klare Ladeindikatoren bereitstellen - Netzwerkfehler mit Fallback-URLs behandeln - Tastaturnavigation unterstützen (Esc zum Schließen)
  • 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
Zuletzt geändert am 12. November 2026