Özel entegrasyon

Zonos Elemanları betiği aşağıdaki URL'de mevcuttur:

<script src="https://js.zonos.com/dist/scripts/loadZonos.js" />

Tarayıcı önbelleklemesini yönetme

Ayrıca, genellikle URL'ye bir zaman damgası veya başka bir benzersiz tanımlayıcı eklemeyi öneriyoruz, böylece script'in tarayıcı tarafından önbelleğe alınmadığından emin olabilirsiniz. Bu, script'in en son sürümünün her zaman yüklenmesini sağlayacaktır. Örneğin:

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://js.zonos.com/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://js.zonos.com/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
      script.addEventListener(
        'load',
        () => {
          // Initialize the script here (instructions in next section)
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>

Zonos JS betiğini yükledikten sonra, bir Zonos API anahtarı ve mağaza kimliğini Zonos.init fonksiyonuna geçirerek doğrulamanız gerekir. Checkout'ı doğrulamak için kullanılan API anahtarları, hassas bilgileri açığa çıkarmadan ön uç kodunda güvenle kullanılabilecek şekilde yayınlanabilir olarak tasarlanmıştır.

Zonos.init({
  // ... other fields
  zonosApiKey: 'API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Zonos JS scriptinin yalnızca izin verilen sitelerde yüklenmesini sağlamak için, "izin verilen alanlar" listesini temel alarak istekleri filtreliyoruz. Bu liste Dashboard'da yapılandırılır. Bu yapılandırma olmadan, Zonos JS scripti düzgün bir şekilde yüklenmek yerine izin hataları döndürecektir.

İzin verilen alanlarınızı güncellemek için:

1. Dashboard -> Ayarlar -> Checkout ayarları sayfasına gidin.
2. İzin verilen alanlar bölümünde, Checkout ile entegre edeceğiniz alan(lar)ı ekleyin.
3. Kaydet butonuna tıklayın.

Hello para birimi bilgilerini gösteren sitenizdeki öğeleri tanımlamak için CSS seçicileri kullanır. Bu seçicileri Zonos.init fonksiyonunun helloSettings.currencyElementSelector özelliğine geçirmeniz gerekecek.

Burada herhangi bir geçerli CSS seçicisi kullanabilirsiniz, örneğin #price, .price birden fazla farklı öğeyi seçmek için.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Hello alışveriş yapanın tarayıcıda kısıtlı ürünleri kontrol etme ve bunların sepete eklenmesini engelleme yeteneğine sahiptir. Bunun çalışabilmesi için, Hello ürün adı ve açıklaması gibi ek ürün bilgilerini bilmelidir; ayrıca "sepete ekle butonu" da gereklidir. Bu bilgileri sayfadan almak için Hello'ya CSS seçicileri geçirebilirsiniz.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    productAddToCartElementSelector: '.add-to-cart',
    productDescriptionElementSelector: '.description',
    productPriceElementSelector: '.price',
    productTitleElementSelector: '.title',
  },
});

Varsayılan olarak, Hello yalnızca ziyaretçi bayrak butonuna tıkladığında açılacaktır. Sayfa yüklendiğinde Hello'yu otomatik olarak açmak istiyorsanız, Zonos betiği yüklendikten sonra Zonos.openHelloDialog() fonksiyonunu çağırabilirsiniz.

Zonos.init({
  // ... other fields
});

Zonos.openHelloDialog();

Zonos JS betiği uluslararası alışveriş yapanları otomatik olarak tanıyacak ve onları Checkout akışına yönlendirecektir. Ancak, tıkladığında Checkout'ı açacak şekilde platformunuzda 'siparişi ver' butonunu yapılandırmanız gerekecektir. Bu, Zonos.init fonksiyonunun checkoutSettings.placeOrderButtonSelector özelliğine bir CSS seçici geçirerek yapılabilir.

Birden fazla sipariş verme butonunuz varsa, hepsini eşleştirecek bir seçici geçirdiğinizden emin olun. Örneğin, #placeOrder, .place-order hem #placeOrder hem de .place-order ile eşleşecektir.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

buildCartDetail geri çağrısı, sepet detaylarını Checkout arayüzünün anlayabileceği ve görüntüleyebileceği bir formatta döndürmekten sorumludur. Bu fonksiyon, müşteri checkout sayfasına geldiği anda çağrılır ve sepet detaylarının Checkout'un ilk sayfasında doğru bir şekilde görüntülenmesini sağlar. Lütfen bunun hesaplamalar için kullanılmadığını - bunun bir sonraki adımda ele alındığını unutmayın.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildCartDetail: async () => {
      // ... Your existing buildCartDetail implementation
      // This should return cart details for UI display
    },
  },
});

Sepet öğesi şeması

buildCartDetail fonksiyonu bir dizi sepet öğesi döndürmelidir. Aşağıda her CartItem nesnesinin yapısını detaylandıran bir tablo bulunmaktadır:

buildLandedCost fonksiyonu landed cost'u güvenli bir şekilde hesaplamaktan sorumludur. Bu fonksiyon, müşteri gönderim bilgilerini girdikten sonra çağrılır. Bu fonksiyon, gönderim ücretlerini ve diğer gerekli maliyetleri hesaplar ve ardından bunlar Checkout'ın sonraki sayfasında görüntülenir.

landed cost hesaplama mantığını sunucu tarafında ele almanız önemlidir, çünkü bu, sepet detaylarının müşterinin tarayıcısına maruz kalmamasını sağlamanın tek yoludur. Sunucusuz bir mimari kullanıyorsanız, landed cost hesaplamasını ele almak için bir sunucusuz fonksiyon kullanabilirsiniz. buildLandedCost fonksiyonu, sunucusuz fonksiyonu/API uç noktasını çağırmalı ve sonucu döndürmelidir.

Sunucu tarafında, Zonos Checkout API'sini kullanarak landed cost'u hesaplamak için aşağıdaki POST isteğini kullanabilirsiniz. credentialToken başlığında Zonos JS scripti için kullandığınız API anahtarını geçirmeniz gerekecektir.

https://v1.route.js.zonos.com/api/zonos-elements/calculate-landed-cost

{
  "billingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  },
  "billingContact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "checkoutSessionId": "xyz789",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "items": [
    {
      "amount": 150,
      "currencyCode": "USD",
      "name": "Product Name",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  }
}

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // This should return the landed cost calculation
    },
  },
});