Przejdź do głównej treści
Komerza Embed SDK w akcji Komerza Embed SDK w akcji

Przegląd

Komerza Embed SDK umożliwia płynną integrację naszego procesu płatności bezpośrednio na Twojej stronie internetowej. Zamiast przekierowywać klientów na osobną stronę płatności, osadzenie tworzy modalne nakładki, które utrzymują użytkowników na Twojej stronie, zapewniając jednocześnie bezpieczny, zoptymalizowany przepływ płatności.

Demo na żywo

Zobacz Embed SDK w akcji z naszą interaktywną demonstracją
Zintegruj również nasz skrypt analityczny, aby przywrócić analizy odwiedzających na swojej niestandardowej stronie dla pełnego wglądu w podróż klienta.

Funkcje

Płynna integracja

Modalna nakładka utrzymuje klientów na Twojej stronie podczas płatności

Lekki

Minimalny pakiet JavaScript bez zewnętrznych zależności

Obsługa motywów

Jasne, ciemne i automatyczne motywy dopasowane do projektu Twojej strony

Zgodny z CSP

Pełne wsparcie polityki bezpieczeństwa treści z integracją nonce

Szybki start

Dodaj następujący skrypt do sekcji <head> swojej strony lub przed zamykającym tagiem </body>:

Metoda 1: Atrybuty danych (zalecana dla prostych przypadków użycia)

Najłatwiejszy sposób dodawania przycisków płatności do Twojej strony. Wystarczy dodać atrybuty danych do dowolnego przycisku lub elementu:

Referencja atrybutów danych

Pozwól klientowi wybrać wariant

data-kmrza-variant-id jest opcjonalny. Jeśli go pominiesz, kasa otworzy się z selektorem wariantu, w którym klient wybiera wariant przed zapłatą.
Przydatne, gdy chcesz mieć jeden przycisk zakupu dla produktu z kilkoma edycjami, pakietami lub okresami. Podaj data-kmrza-variant-id, gdy klient ma trafić od razu na konkretny wariant.

Metoda 2: API JavaScript (dla zaawansowanych przypadków użycia)

Dla większej kontroli użyj API JavaScript, aby programowo otworzyć płatność:

Wiele artykułów

Możesz dodać wiele produktów do płatności jednocześnie:

Kompletny przewodnik po implementacji

Konfiguracja HTML

Oto kompletny przykład strony HTML:

Integracja JavaScript

Referencja API

Komerza.init(options?)

Inicjalizuje osadzenie i automatycznie wiąże wszystkie elementy z atrybutami data-kmrza-*.
Ta sekcja nie została jeszcze przetłumaczona i na razie jest wyświetlana po angielsku.
Options:
  • nonce (optional): CSP nonce for injected styles and scripts
  • preload (optional): Boot the checkout frame ahead of the click (default: true). See below.

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)

Otwiera modalną płatność programowo.

Komerza.close()

Zamyka modalną płatność programowo.

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.

Integracja Next.js

Rozwiązywanie problemów

Płatność nie otwiera się

  1. Upewnij się, że skrypt jest załadowany (atrybut defer jest zalecany)
  2. Sprawdź konsolę przeglądarki pod kątem błędów
  3. Zweryfikuj, czy Twoje ID produktu i wariantu są poprawne
  4. Jeśli używasz atrybutów danych, upewnij się, że Komerza.init() jest wywoływany po załadowaniu DOM
Modal używa wysokiego z-index (9999). Jeśli nadal jest za elementami, sprawdź swój CSS pod kątem konkurujących wartości z-index.

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.

Afiliaci

Komerza Embed SDK obsługuje śledzenie afiliatów od razu po wyjęciu z pudełka. Parametr zapytania ?ref jest automatycznie obsługiwany, a plik cookie kmrza_affiliate jest automatycznie odczytywany.

Polityka bezpieczeństwa treści (CSP)

Najlepsze praktyki

  • Ładuj skrypt SDK asynchronicznie gdy to możliwe
  • Inicjalizuj SDK wcześnie, ale otwieraj modale tylko przy interakcji użytkownika
  • Implementuj odpowiednie stany ładowania dla przycisków zakupu
  • Zapewniaj wyraźne wskaźniki ładowania - Obsługuj awarie sieci gracefully za pomocą URL zastępczych - Wspieraj nawigację klawiaturą (Esc do zamknięcia)
  • Zawsze używaj nagłówków CSP w produkcji
  • Waliduj ID produktu i wariantu przed otwarciem płatności
  • Nigdy nie ujawniaj wrażliwych danych w kodzie po stronie klienta

Wsparcie

Potrzebujesz pomocy z integracją?

Strona demo

Interaktywna demonstracja z przykładami kodu źródłowego

Wsparcie deweloperów

Uzyskaj wsparcie techniczne w kwestiach integracji
Ostatnia modyfikacja 12 listopada 2026