Ana içeriğe geç

Shadow DOM Widget Entegrasyonu

Ödeme formunu kendi sitenizin içine gömmenizi sağlar. Shadow DOM sayesinde widget'ın CSS'i sitenizin stillerini etkilemez, sitenizin stilleri de widget'ı etkilemez.

Shadow DOM Nedir?​

Shadow DOM, bir HTML elemanının içinde izole bir DOM ağacı oluşturur. Bu sayede:

  • Widget'ın CSS'i dışarıyı etkilemez
  • Dışarıdaki CSS widget'ı bozmaz
  • JavaScript event'leri düzgün çalışır
Sizin Siteniz
├── Navbar
├── İçerik
│   └── #paylox-checkout ← Container
│       └── 🔒 Shadow DOM (izole alan)
│           ├── Widget CSS
│           └── Ödeme Formu
└── Footer

Kurulum​

Adım 1: Script Dosyasını Ekleyin​

Sitenizin <head> veya <body> kapanış etiketinden önce şu script'i ekleyin:

<script src="https://checkout.paylox.io/sdk/paylox.js"></script>
Performans İpucu

Script'i async veya defer ile yükleyerek sayfanızın yavaşlamasını önleyebilirsiniz:

<script src="https://checkout.paylox.io/sdk/paylox.js" async></script>

Adım 2: Container (Kapsayıcı) Oluşturun​

Widget'ın render edileceği bir HTML elementi oluşturun:

<div id="paylox-checkout"></div>

Bu element, sayfanızda widget'ın görüneceği yeri belirler. Widget bu elementin içine Shadow DOM olarak eklenir.

Adım 3: Widget'ı Başlatın​

Backend'inizden aldığınız session_id ile widget'ı başlatın:

<script>
  // Script yüklendikten sonra çalıştığından emin olun
  document.addEventListener("DOMContentLoaded", function() {
    Paylox.init({
      sessionId: "ses_a1b2c3d4e5f6g7h8i9j0k1l2",
      container: "#paylox-checkout",
      onSuccess: function(data) {
        console.log("Ödeme başarılı!", data);
        // Kullanıcıyı başarı sayfasına yönlendir
        window.location.href = "/payment/success?order_id=" + data.order_id;
      },
      onFail: function(error) {
        console.log("Ödeme başarısız:", error);
        // Hata mesajı göster
        alert("Ödeme başarısız: " + error.message);
      },
      onClose: function() {
        console.log("Widget kapatıldı");
      }
    });
  });
</script>

Tam Çalışan Örnek​

Aşağıdaki HTML dosyasını kopyalayıp doğrudan tarayıcıda açabilirsiniz:

<!DOCTYPE html>
<html lang="tr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ödeme Sayfası</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
            background: #f5f5f5;
        }
        h1 {
            color: #333;
        }
        .order-summary {
            background: white;
            padding: 20px;
            border-radius: 8px;
            margin-bottom: 20px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }
        #paylox-checkout {
            min-height: 400px;
        }
    </style>
</head>
<body>
    <h1>Sipariş Ödemesi</h1>

    <div class="order-summary">
        <h3>Sipariş Özeti</h3>
        <p>Ürün: Kablosuz Kulaklık</p>
        <p>Tutar: <strong>150.00 TL</strong></p>
    </div>

    <!-- Paylox Widget Buraya Yüklenecek -->
    <div id="paylox-checkout"></div>

    <!-- Paylox SDK -->
    <script src="https://checkout.paylox.io/sdk/paylox.js"></script>
    <script>
        // session_id'yi backend'inizden almalısınız
        // Bu örnek için sabit bir değer kullanıyoruz
        const SESSION_ID = "ses_BURAYA_SESSION_ID_GELECEK";

        Paylox.init({
            sessionId: SESSION_ID,
            container: "#paylox-checkout",
            onSuccess: function(data) {
                alert("Ödeme başarılı! Sipariş No: " + data.order_id);
                window.location.href = "/tesekkurler";
            },
            onFail: function(error) {
                alert("Ödeme başarısız: " + error.message);
            }
        });
    </script>
</body>
</html>

Init Parametreleri​

ParametreTipZorunluAçıklama
sessionIdstring✅Backend'den aldığınız checkout session ID
containerstring❌CSS seçici. Varsayılan: #paylox-checkout
onSuccessfunction❌Ödeme başarılı olduğunda çağrılır
onFailfunction❌Ödeme başarısız olduğunda çağrılır
onClosefunction❌Widget kapatıldığında çağrılır

Widget'ı Kaldırma​

Widget'ı programatik olarak kaldırmak için:

Paylox.destroy();

Sık Sorulan Sorular​

Widget neden sayfamın stillerini bozmuyor?​

Shadow DOM sayesinde widget'ın tüm CSS'i izole bir alan içinde çalışır. Widget'ın stilleri sayfanıza sızmaz, sayfanızın stilleri de widget'a girmez.

Birden fazla widget aynı sayfada kullanılabilir mi?​

Hayır. Aynı anda sadece bir Paylox widget aktif olabilir. İkinci bir widget başlatmadan önce Paylox.destroy() çağırın.

Widget mobilde çalışır mı?​

Evet. Widget responsive tasarıma sahiptir ve mobil cihazlarda sorunsuz çalışır.

Content Security Policy (CSP) ayarları gerekli mi?​

Evet. Şu domainleri whitelist'e eklemeniz gerekir:

script-src: https://checkout.paylox.io
connect-src: https://api.paylox.io

Sorun Giderme​

SorunÇözüm
Widget görünmüyorContainer element'in DOM'da var olduğundan emin olun
"Session not found" hatasıSession ID'nin doğru ve süresinin dolmadığından emin olun
CSS bozuk görünüyorScript'in doğru yüklendiğini console'dan kontrol edin
CORS hatasıAPI URL'inizin CORS ayarlarında sitenizin domaininin ekli olduğundan emin olun