Embed SDK

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

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

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:

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

<script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
<script>
  // Zainicjuj osadzenie, aby powiązać wszystkie przyciski z atrybutami danych
  document.addEventListener("DOMContentLoaded", () => {
    Komerza.init();
  });
</script>

Referencja atrybutów danych

Atrybut	Wymagany	Opis	Przykład
`data-kmrza-product-id`	✅ Tak	ID produktu z Komerza	`"0f6294be-25d6-4ced-96df-7d500608c54d"`
`data-kmrza-variant-id`	❌ Nie	ID wariantu z Komerza. Pomiń, aby klient wybrał sam - zobacz poniżej	`"96f846e5-5f22-46a2-97b3-a1c88f685577"`
`data-kmrza-quantity`	❌ Nie	Ilość do zakupu (domyślnie: 1)	`"2"`
`data-kmrza-theme`	❌ Nie	Tryb motywu: `light`, `dark` lub `auto` (domyślnie: `auto`)	`"dark"`
`data-kmrza-return-url`	❌ Nie	Niestandardowy URL do przekierowania po płatności	`"https://example.com/dziekujemy"`
`data-kmrza-email`	❌ Nie	Wstępnie wypełnij adres e-mail klienta	`"klient@example.com"`
`data-kmrza-coupon-code`	❌ Nie	Wstępnie wypełnij i automatycznie zastosuj kod kuponu	`"SAVE20"`
`data-kmrza-metadata`	❌ Nie	Ciąg JSON niestandardowych metadanych klucz-wartość	`"{"campaign":"summer"}"`

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ą.

<button data-kmrza-product-id="YOUR_PRODUCT_ID">Kup teraz</button>

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ść:

<button id="checkout-btn">Kup teraz</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' lub 'auto'
    });
  });
</script>

Wiele artykułów

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

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

Kompletny przewodnik po implementacji

Konfiguracja HTML

Oto kompletny przykład strony HTML:

<!DOCTYPE html>
<html lang="pl">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mój Sklep</title>

    <!-- Nagłówek CSP (zalecany) -->
    <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>Niesamowity produkt</h1>
      <p>Cena: 29,99 zł</p>

      <!-- Twój przycisk zakupu -->
      <button id="buy-now" class="buy-button">Kup teraz</button>
    </div>

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

    <script nonce="abc123">
      // Twój kod integracji tutaj
    </script>
  </body>
</html>

Integracja JavaScript

Podstawowa integracja
Zaawansowana integracja
Integracja React

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

class CheckoutManager {
  constructor() {
    this.isInitialized = false;
    this.init();
  }
  
  init() {
    Komerza.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') Komerza.close(); });
  }
  
  handlePurchase(button) {
    const { productId, variantId } = button.dataset;
    const quantity = parseInt(button.dataset.quantity) || 1;
    if (!productId || !variantId) { console.error('Brak ID produktu lub wariantu'); return; }
    try {
      Komerza.open({ items: [{ productId, variantId, quantity }], theme: this.getTheme() });
    } catch (error) {
      console.error('Nie udało się otworzyć płatności:', error);
      window.location.href = `https://checkout.komerza.com/product/${productId}/${variantId}?qty=${quantity}`;
    }
  }
  
  getTheme() { return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; }
  getCSPNonce() { return document.querySelector('script[nonce]')?.getAttribute('nonce') ?? null; }
}

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.Komerza.init(); setIsEmbedReady(true); };
    document.head.appendChild(script);
    return () => document.head.removeChild(script);
  }, []);
  
  const handleBuyClick = () => {
    if (!isEmbedReady) return;
    window.Komerza.open({
      items: [{ productId: 'prod_123', variantId: 'var_456', quantity: 1 }],
      theme: 'auto'
    });
  };
  
  return (
    <div className="product-page">
      <h1>Niesamowity produkt</h1>
      <p>Cena: 29,99 zł</p>
      <button onClick={handleBuyClick} disabled={!isEmbedReady} className="buy-button">
        {isEmbedReady ? 'Kup teraz' : 'Ładowanie...'}
      </button>
    </div>
  );
};

export default ProductPage;

Referencja API

`Komerza.init(options?)`

Inicjalizuje osadzenie i automatycznie wiąże wszystkie elementy z atrybutami data-kmrza-*.

Komerza.init({
  nonce: "TWÓJ_NONCE_CSP", // Opcjonalnie: dla polityki bezpieczeństwa treści
});

`Komerza.open(options)`

Otwiera modalną płatność programowo.

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()`

Zamyka modalną płatność programowo.

Komerza.close();

Integracja Next.js

// 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}>Kup teraz</button>
    </>
  );
}

Rozwiązywanie problemów

Płatność nie otwiera się

Upewnij się, że skrypt jest załadowany (atrybut defer jest 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 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.

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)

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

Komerza.init({ nonce: "TWÓJ_NONCE" });

Najlepsze praktyki

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

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

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

Pierwsze Kroki

Konfiguracja Sklepu

Przewodniki Integracji

Konfiguracja Płatności

Przegląd

Demo na żywo

Funkcje

Płynna integracja

Lekki

Obsługa motywów

Zgodny z CSP

Szybki start

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

Referencja atrybutów danych

Pozwól klientowi wybrać wariant

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

Wiele artykułów

Kompletny przewodnik po implementacji

Konfiguracja HTML

Integracja JavaScript

Referencja API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Integracja Next.js

Rozwiązywanie problemów

Płatność nie otwiera się

Afiliaci

Polityka bezpieczeństwa treści (CSP)

Najlepsze praktyki

Wsparcie

Strona demo

Wsparcie deweloperów

​Przegląd

Demo na żywo

​Funkcje

Płynna integracja

Lekki

Obsługa motywów

Zgodny z CSP

​Szybki start

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

​Referencja atrybutów danych

​Pozwól klientowi wybrać wariant

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

​Wiele artykułów

​Kompletny przewodnik po implementacji

​Konfiguracja HTML

​Integracja JavaScript

​Referencja API

​Komerza.init(options?)

​Komerza.open(options)

​Komerza.close()

​Integracja Next.js

​Rozwiązywanie problemów

​Płatność nie otwiera się

​Modal pojawia się za innymi elementami

​Afiliaci

​Polityka bezpieczeństwa treści (CSP)

​Najlepsze praktyki

​Wsparcie

Strona demo

Wsparcie deweloperów

Przegląd

Funkcje

Szybki start

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

Referencja atrybutów danych

Pozwól klientowi wybrać wariant

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

Wiele artykułów

Kompletny przewodnik po implementacji

Konfiguracja HTML

Integracja JavaScript

Referencja API

`Komerza.init(options?)`

`Komerza.open(options)`

`Komerza.close()`

Integracja Next.js

Rozwiązywanie problemów

Płatność nie otwiera się

Modal pojawia się za innymi elementami

Afiliaci

Polityka bezpieczeństwa treści (CSP)

Najlepsze praktyki

Wsparcie