DOCS

Integrasi kustom

Masuk
Pesan demo
Checkout•
BerandaEcommerce global Integrasi Integrasikan Checkout Integrasi kustom

Integrasi kustom

Bangun integrasi Checkout end-to-end ke dalam situs kustom Anda.

Panduan ini mencakup aspek teknis untuk menyelesaikan integrasi penuh Zonos Checkout ke dalam situs atau platform kustom Anda. Ini ditujukan untuk pengembang yang nyaman bekerja dengan JavaScript dan memiliki pengalaman dalam pengembangan frontend. Semua langkah diperlukan kecuali dinyatakan sebaliknya.

Prasyarat


Instal skrip JS Zonos 

Integrasi kustom Anda perlu menyertakan cuplikan JavaScript Zonos. Skrip ini bertanggung jawab untuk merender UI Checkout, Zonos Hello, menangani pemrosesan pembayaran, dan menangani deteksi geo-IP pengunjung.

1

Instal cuplikan JS Zonos

Skrip Elemen Zonos tersedia di URL berikut:

Zonos cuplikan JS

1
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />

Menangani caching browser

Kami juga biasanya merekomendasikan untuk menambahkan cap waktu atau pengidentifikasi unik lainnya ke URL untuk memastikan bahwa skrip tidak di-cache oleh browser. Ini akan memastikan bahwa versi terbaru dari skrip selalu dimuat. Sebagai contoh:

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

Autentikasi Zonos JS snippet

Setelah Anda memuat skrip JS Zonos, Anda perlu mengautentikasinya dengan mengirimkan kunci Zonos API dan ID toko ke dalam fungsi Zonos.init. Kunci API yang digunakan untuk mengautentikasi Checkout dirancang untuk dapat dipublikasikan, yang berarti dapat digunakan dengan aman dalam kode frontend tanpa mengekspos informasi sensitif.

Zonos JS snippet

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

Atur domain yang diizinkan

Untuk memastikan bahwa skrip JS Zonos hanya dimuat di situs yang diizinkan, kami memfilter permintaan berdasarkan daftar "domain yang diizinkan". Daftar ini dikonfigurasi di Dashboard. Tanpa konfigurasi ini, skrip JS Zonos akan mengembalikan kesalahan izin alih-alih dimuat dengan benar.

Untuk memperbarui domain yang diizinkan Anda:

  1. Pergi ke Dashboard -> Pengaturan -> pengaturan Checkout.
  2. Di bawah bagian Domain yang diizinkan, tambahkan domain tempat Anda akan mengintegrasikan Checkout.
  3. Klik Simpan.

Siapkan Zonos Hello 

Setelah Anda menyiapkan skrip JS Zonos, Anda perlu mengonfigurasi Hello agar berfungsi dengan situs Anda. Hello bertanggung jawab untuk mendeteksi lokasi, bahasa, dan mata uang pengunjung, serta menampilkan informasi yang sesuai kepada mereka. Hello diperlukan saat menggunakan Checkout.

Anda dapat mengonfigurasi semua pengaturan Hello baik di Dashboard maupun di skrip JS Zonos. Jika Anda telah mengonfigurasi Hello di Dashboard, skrip akan memuat pengaturan tersebut dan menggunakannya. Jika Anda menentukan nilai apa pun di properti helloSettings dari fungsi Zonos.init, skrip akan menggunakan nilai tersebut sebagai gantinya.

1

Konfigurasi konversi mata uang

Hello menggunakan pemilih CSS untuk mengidentifikasi elemen di situs Anda yang menampilkan informasi mata uang. Anda perlu meneruskan pemilih ini ke properti helloSettings.currencyElementSelector dari fungsi Zonos.init.

Anda dapat menggunakan pemilih CSS yang valid di sini, misalnya #price, .price untuk memilih beberapa elemen yang berbeda.

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

Opsional — Buka secara otomatis Hello saat halaman dimuat

Secara default, Hello hanya akan terbuka ketika pengunjung mengklik tombol bendera. Jika Anda ingin membuka Hello secara otomatis saat halaman dimuat, Anda dapat memanggil fungsi Zonos.openHelloDialog() setelah skrip Zonos dimuat.

Zonos JS snippet

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

Siapkan Zonos Checkout 

Setelah Hello dikonfigurasi, Anda perlu menyiapkan Checkout agar dapat bekerja dengan situs Anda. Checkout bertanggung jawab untuk memungkinkan pelanggan memasukkan informasi pengiriman mereka, menghitung landed cost, dan menyelesaikan pesanan.

Checkout akan berbagi data kontekstual dengan Hello, seperti lokasi pengunjung, bahasa, dan mata uang. Ini memastikan bahwa pengalaman pelanggan konsisten di seluruh proses belanja.

Anda dapat mengonfigurasi semua pengaturan Checkout baik di Dashboard maupun di skrip JS Zonos. Jika Anda telah mengonfigurasi Checkout di Dashboard, skrip akan memuat pengaturan tersebut dan menggunakannya. Jika Anda menentukan nilai apa pun di properti checkoutSettings dari fungsi Zonos.init, skrip akan menggunakan nilai tersebut sebagai gantinya.

1

Konfigurasi tombol 'tempatkan pesanan'

Skrip JS Zonos akan secara otomatis mengenali pembeli internasional dan mengarahkan mereka ke alur Checkout. Namun, Anda perlu mengonfigurasi tombol 'tempatkan pesanan' di platform Anda untuk membuka Checkout saat diklik. Ini dapat dilakukan dengan mengirimkan pemilih CSS ke properti checkoutSettings.placeOrderButtonSelector dari fungsi Zonos.init.

Jika Anda memiliki beberapa tombol yang dapat digunakan untuk melakukan pemesanan, pastikan untuk mengirimkan pemilih yang akan mencocokkan semuanya. Misalnya, #placeOrder, .place-order akan mencocokkan baik #placeOrder maupun .place-order.

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

Buat detail keranjang dengan aman di sisi server

Untuk menampilkan detail keranjang kepada pelanggan, Anda perlu membuat fungsi di sisi server yang akan memanggil API Zonos untuk membuat keranjang, dan kemudian mengirimkan ID keranjang tersebut kembali ke frontend Anda. Ini akan memastikan bahwa detail keranjang tidak terekspos kepada pelanggan dengan cara yang dapat dimanipulasi.

Panggilan API backend Anda akan menggunakan token kredensial GraphQL rahasia, yang berbeda dari token publik yang Anda gunakan untuk mengautentikasi skrip JS Zonos. Token ini dapat diambil di Dashboard -> Settings -> Integrasi. Token rahasia perlu dikirimkan sebagai header dalam panggilan API Anda.

Mutasi cartCreate menerima daftar item, yang harus diformat sesuai dengan skema item keranjang.

Contoh pembuatan keranjang di sisi server

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
}

Kami menyarankan untuk membuat endpoint API di sisi server Anda dan kemudian memanggil endpoint tersebut dari integrasi JS frontend Anda, yang dijelaskan di langkah berikutnya.

3

Kirim ID keranjang ke Checkout melalui frontend

Setelah Anda membuat keranjang di sisi server Anda, Anda perlu mengirimkan ID keranjang ke skrip JS Zonos. Ini dapat dilakukan dengan menggunakan callback createCartId yang merupakan bagian dari fungsi Zonos.init. Checkout kemudian akan dengan aman mengambil detail keranjang dari Zonos saat dibuka, mencegah adanya manipulasi pada keranjang.

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

Apakah halaman ini membantu?

Pesan demo
© 2025 Zonoszonos.com
Di halaman ini:
  • Integrasi kustom
  • Instal skrip JS Zonos
  • Siapkan Zonos Hello
  • Siapkan Zonos Checkout