

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ą.
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
- Podstawowa integracja
- Zaawansowana integracja
- Integracja React
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.
nonce(optional): CSP nonce for injected styles and scriptspreload(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 withdata-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:
Komerza.init() yourself, set it on the tag instead:
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:
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ę
- Upewnij się, że skrypt jest załadowany (atrybut
deferjest zalecany) - Sprawdź konsolę przeglądarki pod kątem błędów
- Zweryfikuj, czy Twoje ID produktu i wariantu są poprawne
- Jeśli używasz atrybutów danych, upewnij się, że
Komerza.init()jest wywoływany po załadowaniu DOM
Modal pojawia się za innymi elementami
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, passpreload: 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
Wydajność
Wydajność
- Ł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
Doświadczenie użytkownika
Doświadczenie użytkownika
- Zapewniaj wyraźne wskaźniki ładowania - Obsługuj awarie sieci gracefully za pomocą URL zastępczych - Wspieraj nawigację klawiaturą (Esc do zamknięcia)
Bezpieczeństwo
Bezpieczeństwo
- 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