DOCS

Özel entegrasyon

Checkout•
AnasayfaKüresel e-ticaret Entegrasyon Checkout'ı entegre edin Özel entegrasyon

Özel entegrasyon

Özel sitenize uçtan uca bir Checkout entegrasyonu oluşturun.

Bu kılavuz, Zonos Checkout'ın özel sitenize veya platformunuza tam entegrasyonunu tamamlamanın teknik yönlerini kapsar. JavaScript ile çalışmaya aşina olan ve ön yüz geliştirme deneyimi olan geliştiriciler için tasarlanmıştır. Tüm adımlar, aksi belirtilmedikçe gereklidir.

Ön koşullar


Zonos JS betiğini yükleyin 

Özel entegrasyonunuzun Zonos JavaScript parçasını içermesi gerekecek. Bu betik, Checkout UI'sını, Zonos Hello'yı oluşturmak, ödeme işlemlerini yönetmek ve ziyaretçi geo-IP tespitini gerçekleştirmekten sorumludur.

1

Zonos JS parçasını yükleyin

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

Zonos JS parçası

1
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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:

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

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

Zonos JS parçasını doğrulayın

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 JS parçası

1
2
3
4
5
6
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
});
3

İzin verilen alan adlarını ayarlayın

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

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

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

Zonos Hello'yu ayarlayın 

Zonos JS betiğini ayarladıktan sonra, Hello'yu sitenizle çalışacak şekilde yapılandırmanız gerekir. Hello ziyaretçinin konumunu, dilini ve para birimini tespit etmekten ve onlara uygun bilgileri göstermekten sorumludur. Hello Checkout kullanırken gereklidir.

Tüm Hello ayarlarını hem Dashboard'da hem de Zonos JS betiğinde yapılandırabilirsiniz. Eğer Hello'yu Dashboard'da zaten yapılandırdıysanız, betik bu ayarları yükleyecek ve kullanacaktır. Zonos.init fonksiyonunun helloSettings özelliğinde herhangi bir değer belirtirseniz, betik bu değerleri kullanacaktır.

1

Para birimi dönüşümünü yapılandırı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 JS snippet

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Opsiyonel — Sayfa yüklendiğinde Hello'yu otomatik olarak aç

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 JS snippet

1
2
3
4
5
6
7
8
9
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Zonos Checkout'u ayarlayın 

Hello yapılandırıldıktan sonra, Checkout'u sitenizle çalışacak şekilde ayarlamanız gerekir. Checkout müşteriyle gönderim bilgilerini girmesine, landed cost hesaplamasına ve siparişi tamamlamasına olanak tanır.

Checkout ziyaretçinin konumu, dili ve para birimi gibi bağlamsal verileri Hello ile paylaşacaktır. Bu, müşterinin deneyiminin alışveriş süreci boyunca tutarlı olmasını sağlar.

Tüm Checkout ayarlarını hem Dashboard'da hem de Zonos JS betiğinde yapılandırabilirsiniz. Eğer Checkout'u Dashboard'da zaten yapılandırdıysanız, betik bu ayarları yükleyecek ve kullanacaktır. Zonos.init fonksiyonunun checkoutSettings özelliğinde herhangi bir değer belirtirseniz, betik bu değerleri kullanacaktır.

1

'siparişi ver' butonunu yapılandırın

Zonos JS betiği uluslararası alışveriş yapanları otomatik olarak tanıyacak ve onları Checkout akışına yönlendirecektir. Ancak, platformunuzda 'siparişi ver' butonunu tıkladığında Checkout'u açacak şekilde 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 JS snippet

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});
2

Sepet detaylarını güvenli bir şekilde sunucu tarafında oluşturma

Müşteriye sepet detaylarını gösterebilmek için, Zonos API'sini çağırarak bir sepet oluşturacak bir sunucu tarafı fonksiyonu oluşturmanız gerekmektedir ve ardından bu sepet ID'sini ön yüzünüze geri iletmelisiniz. Bu, sepet detaylarının müşteriye manipüle edilebilecek bir şekilde ifşa edilmemesini sağlayacaktır.

Arka uç API çağrınız, Zonos JS scriptini kimlik doğrulamak için kullandığınız genel token'dan farklı olan gizli bir GraphQL kimlik bilgisi token'ı kullanacaktır. Bu token, Dashboard -> Settings -> Integrations bölümünden alınabilir. Gizli token, API çağrınızda bir başlık olarak iletilmelidir.

cartCreate mutasyonu, sepet öğesi şeması ile formatlanması gereken bir öğe listesi kabul eder.

Örnek sunucu tarafı sepet oluşturma

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
// Create new cart from serverside
async function createCart() {
  /**
   * Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
   * */
  const graphql = JSON.stringify({
    query: `
mutation cartCreate($input: CartCreateInput!){
  cartCreate(input: $input) {
    id
    adjustments {
      amount
      currencyCode
      description
      productId
      sku
      type
    }
    items {
      id
      name
      amount
      currencyCode
      quantity
      sku
      description
      metadata {
        key
        value
      }
    }
    metadata {
      key
      value
    }
  }
}`,
    variables: {
      /**
       * input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
       */
      input: {
        /**
         * Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
         */
        adjustments: [
          {
            amount: -10,
            currencyCode: 'USD',
            /**
             * Enum value: https://zonos.com/developer/types/CartAdjustmentType
             */
            type: 'CART_TOTAL',
          },
        ],
        /**
         * Cart item input: https://zonos.com/developer/types/ItemInput
         */
        items: [
          {
            name: 'Item 1',
            amount: 150.99,
            currencyCode: 'USD',
            description: 'Item 1 description',
            quantity: 2,
          },
        ],
        /**
         * Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
         */
        metadata: [
          {
            key: 'key1',
            value: 'value1',
          },
        ],
      },
    },
  });

  const response = await fetch('https://api.zonos.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      credentialToken: 'credential_live_xxxxxxxxx', // Replace with your actual SECRET credential token (found in Dashboard)
    },
    body: graphql,
  });

  const { data } = await response.json();
  return data.cartCreate.id; // Return the cart ID to your frontend
}

Önerimiz, sunucu tarafınızda bir API uç noktası oluşturmak ve ardından bu uç noktanın ön yüz JS entegrasyonunuzdan çağrılmasını sağlamaktır; bu, bir sonraki adımda detaylandırılmıştır.

3

Sepet ID'sini Checkout'a ön yüz aracılığıyla iletin

Sunucu tarafınızda bir sepet oluşturduktan sonra, sepet ID'sini Zonos JS betiğine iletmeniz gerekmektedir. Bu, Zonos.init fonksiyonunun bir parçası olan createCartId geri çağrısını kullanarak yapılabilir. Checkout açıldığında, sepet detaylarını Zonos'dan güvenli bir şekilde alacak ve sepetin herhangi bir şekilde değiştirilmesini önleyecektir.

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch('https://api.merchant.com/api/get-cart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});

Bu sayfa yardımcı oldu mu?

Bir demo rezervasyonu yap

Sorular?

Destek al
© 2025 Zonoszonos.com
Bu sayfada:
  • Özel entegrasyon
  • Zonos JS betiğini yükleyin
  • Zonos Hello'yu ayarlayın
  • Zonos Checkout'u ayarlayın