Tích hợp tùy chỉnh

Tập lệnh Zonos Elements có sẵn tại URL sau:

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

Xử lý bộ nhớ cache của trình duyệt

Chúng tôi cũng thường khuyên nên thêm một dấu thời gian hoặc một định danh duy nhất khác vào URL để đảm bảo rằng tập lệnh không bị bộ nhớ cache bởi trình duyệt. Điều này sẽ đảm bảo rằng phiên bản mới nhất của tập lệnh luôn được tải. Ví dụ:

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

Khi bạn đã tải đoạn mã JS của Zonos, bạn cần xác thực nó bằng cách truyền một khóa API của Zonos và ID cửa hàng vào hàm Zonos.init. Các khóa API được sử dụng để xác thực Checkout được thiết kế để có thể công khai, có nghĩa là chúng có thể được sử dụng an toàn trong mã frontend mà không làm lộ bất kỳ thông tin nhạy cảm nào.

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

Để đảm bảo rằng script JS của Zonos chỉ được tải trên các trang web được phép, chúng tôi lọc các yêu cầu dựa trên danh sách "miền được phép". Danh sách này được cấu hình trong Dashboard. Nếu không có cấu hình này, script JS của Zonos sẽ trả về lỗi quyền thay vì tải đúng cách.

Để cập nhật các miền được phép của bạn:

1. Đi tới Dashboard -> Cài đặt -> cài đặt Checkout.
2. Dưới phần Miền được phép, thêm miền mà bạn sẽ tích hợp Checkout.
3. Nhấn Lưu.

Hello sử dụng các bộ chọn CSS để xác định các phần tử trên trang web của bạn hiển thị thông tin tiền tệ. Bạn sẽ cần truyền các bộ chọn này vào thuộc tính helloSettings.currencyElementSelector của hàm Zonos.init.

Bạn có thể sử dụng bất kỳ bộ chọn CSS hợp lệ nào ở đây, ví dụ #price, .price để chọn nhiều phần tử khác nhau.

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

Hello có khả năng kiểm tra các mặt hàng bị hạn chế khi người mua sắm duyệt và ngăn chúng được thêm vào giỏ hàng. Để điều này hoạt động, Hello cần biết thêm thông tin về mặt hàng như tên và mô tả, cũng như "nút thêm vào giỏ hàng". Bạn có thể truyền các bộ chọn CSS cho Hello để cho phép nó thu thập thông tin này từ trang.

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

Theo mặc định, Hello chỉ mở khi người truy cập nhấp vào nút cờ. Nếu bạn muốn tự động mở Hello khi trang tải, bạn có thể gọi hàm Zonos.openHelloDialog() sau khi script Zonos đã được tải.

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

Zonos.openHelloDialog();

Tập lệnh JS của Zonos sẽ tự động nhận diện người mua quốc tế và hướng dẫn họ đến quy trình Checkout. Tuy nhiên, bạn sẽ cần cấu hình nút 'đặt hàng' trên nền tảng của bạn để mở Checkout khi được nhấp. Điều này có thể được thực hiện bằng cách truyền một bộ chọn CSS vào thuộc tính checkoutSettings.placeOrderButtonSelector của hàm Zonos.init.

Nếu bạn có nhiều nút có thể được sử dụng để đặt hàng, hãy đảm bảo truyền vào một bộ chọn sẽ khớp với tất cả chúng. Ví dụ, #placeOrder, .place-order sẽ khớp với cả #placeOrder và .place-order.

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

Callback buildCartDetail chịu trách nhiệm trả về chi tiết giỏ hàng ở định dạng mà giao diện Checkout có thể hiểu và hiển thị. Hàm này được gọi ngay khi khách hàng đến trang checkout, đảm bảo rằng chi tiết giỏ hàng được hiển thị chính xác trên trang đầu tiên của Checkout. Xin lưu ý rằng điều này không được sử dụng cho các phép tính - điều đó sẽ được xử lý ở bước tiếp theo.

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

Sơ đồ mặt hàng trong giỏ hàng

Hàm buildCartDetail nên trả về một mảng các mặt hàng trong giỏ hàng. Dưới đây là bảng chi tiết cấu trúc của mỗi đối tượng CartItem:

Hàm buildLandedCost xử lý việc tính toán an toàn landed cost. Nó được gọi sau khi khách hàng nhập thông tin giao hàng của họ. Hàm này tính toán các mức phí vận chuyển và các chi phí cần thiết khác, sau đó được hiển thị trên trang tiếp theo của Checkout.

Điều quan trọng là bạn phải xử lý logic tính toán landed cost ở phía máy chủ, vì đây là cách duy nhất để đảm bảo rằng chi tiết giỏ hàng không bị lộ ra trình duyệt của khách hàng. Nếu bạn đang sử dụng kiến trúc không máy chủ, bạn có thể sử dụng một hàm không máy chủ để xử lý việc tính toán landed cost. Hàm buildLandedCost chỉ cần gọi hàm/API không máy chủ và trả về kết quả.

Ở phía máy chủ, bạn có thể sử dụng API Zonos Checkout để tính toán landed cost bằng cách sử dụng yêu cầu POST sau. Bạn sẽ cần truyền khóa API mà bạn đã sử dụng cho tập lệnh JS của Zonos trong tiêu đề 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
    },
  },
});