Integrasi kustom

Skrip Elemen Zonos tersedia di URL berikut:

<script src="https://js.zonos.com/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:

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

Setelah Anda memuat skrip Zonos JS, 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.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
});

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.

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.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Hello memiliki kemampuan untuk memeriksa item yang dibatasi saat pembeli menjelajah dan mencegahnya ditambahkan ke keranjang. Agar ini berfungsi, Hello perlu mengetahui informasi tambahan tentang item seperti nama dan deskripsi, serta "tombol tambah ke keranjang". Anda dapat mengirimkan pemilih CSS ke Hello untuk memungkinkannya mengambil informasi ini dari halaman.

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

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.init({
  // ... other fields
});

Zonos.openHelloDialog();

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.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

Callback buildCartDetail bertanggung jawab untuk mengembalikan detail keranjang dalam format yang dapat dipahami dan ditampilkan oleh antarmuka Checkout. Fungsi ini dipanggil segera setelah pelanggan tiba di halaman checkout, memastikan bahwa detail keranjang ditampilkan dengan akurat di halaman pertama Checkout. Harap dicatat bahwa ini tidak digunakan untuk perhitungan - itu ditangani di langkah berikutnya.

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

Skema item keranjang

Fungsi buildCartDetail harus mengembalikan array item keranjang. Di bawah ini adalah tabel yang merinci struktur setiap objek CartItem:

Fungsi buildLandedCost menangani perhitungan landed cost dengan aman. Fungsi ini dipanggil setelah pelanggan memasukkan informasi pengiriman mereka. Fungsi ini menghitung tarif pengiriman dan biaya lain yang diperlukan, yang kemudian ditampilkan di halaman berikutnya dari Checkout.

Penting untuk menangani logika perhitungan landed cost di sisi server, karena ini adalah satu-satunya cara untuk memastikan bahwa detail keranjang tidak terpapar ke browser pelanggan. Jika Anda menggunakan arsitektur tanpa server, Anda dapat menggunakan fungsi tanpa server untuk menangani perhitungan landed cost. Fungsi buildLandedCost harus cukup memanggil fungsi/API endpoint tanpa server dan mengembalikan hasilnya.

Di sisi server, Anda dapat menggunakan API Zonos Checkout untuk menghitung landed cost dengan menggunakan permintaan POST berikut. Anda perlu mengirimkan kunci API yang telah Anda gunakan untuk skrip JS Zonos di header credentialToken.

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