Cài đặt tập lệnh JS của Zonos
Tích hợp tùy chỉnh của bạn sẽ cần bao gồm đoạn mã JavaScript của Zonos. Tập lệnh này chịu trách nhiệm hiển thị giao diện người dùng Checkout, Zonos Hello, xử lý thanh toán và xử lý phát hiện geo-IP của khách truy cập.
Cài đặt đoạn mã JS của Zonos
Tập lệnh Zonos Elements có sẵn tại URL sau:
Zonos JS snippet
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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ụ:
Zonos JS snippet
<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>
Xác thực đoạn mã JS của Zonos
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 vào 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 JS snippet
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
});
Đặt miền được phép
Để đả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:
- Đi tới Dashboard -> Cài đặt -> cài đặt Checkout.
- Dưới phần Miền được phép, thêm miền mà bạn sẽ tích hợp Checkout.
- Nhấn Lưu.
Thiết lập Zonos Hello
Khi bạn đã thiết lập script JS của Zonos, bạn cần cấu hình Hello để hoạt động với trang web của bạn. Hello chịu trách nhiệm phát hiện vị trí, ngôn ngữ và tiền tệ của khách truy cập, và hiển thị thông tin phù hợp cho họ. Hello là cần thiết khi sử dụng Checkout.
Bạn có thể cấu hình tất cả các cài đặt của Hello trong cả Dashboard và script JS của Zonos. Nếu bạn đã cấu hình Hello trong Dashboard, script sẽ tải các cài đặt đó và sử dụng chúng. Nếu bạn chỉ định bất kỳ giá trị nào trong thuộc tính helloSettings
của hàm Zonos.init
, script sẽ sử dụng các giá trị đó thay thế.
Cấu hình chuyển đổi tiền tệ
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 JS snippet
Zonos.init({
// ... other fields
helloSettings: {
// ... other fields
currencyElementSelector: '#price, .price', // Replace with your actual selector
},
});
Tùy chọn — Tự động mở Hello khi tải trang
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()
một lần khi script Zonos đã được tải.
Zonos JS snippet
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
Thiết lập Zonos Checkout
Khi Hello đã được cấu hình, bạn cần thiết lập Checkout để hoạt động với trang web của bạn. Checkout chịu trách nhiệm cho phép khách hàng nhập thông tin giao hàng, tính toán landed cost, và hoàn tất đơn hàng.
Checkout sẽ chia sẻ dữ liệu ngữ cảnh với Hello, chẳng hạn như vị trí của khách truy cập, ngôn ngữ và tiền tệ. Điều này đảm bảo rằng trải nghiệm của khách hàng là nhất quán trong toàn bộ quá trình mua sắm.
Bạn có thể cấu hình tất cả các cài đặt của Checkout trong cả Dashboard và tập lệnh JS của Zonos. Nếu bạn đã cấu hình Checkout trong Dashboard, tập lệnh sẽ tải các cài đặt đó và sử dụng chúng. Nếu bạn chỉ định bất kỳ giá trị nào trong thuộc tính checkoutSettings
của hàm Zonos.init
, tập lệnh sẽ sử dụng các giá trị đó thay thế.
Cấu hình nút 'đặt hàng'
Tập lệnh JS của Zonos sẽ tự động nhận diện các khách hàng 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 JS snippet
Zonos.init({
// ... other fields
checkoutSettings: {
// ... other fields
placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
},
});
Tạo chi tiết giỏ hàng một cách an toàn trên máy chủ
Để hiển thị chi tiết giỏ hàng cho khách hàng, bạn cần tạo một chức năng trên máy chủ sẽ gọi API Zonos để tạo một giỏ hàng, và sau đó truyền lại ID giỏ hàng đó cho frontend của bạn. Điều này sẽ đảm bảo rằng chi tiết giỏ hàng không bị lộ ra cho khách hàng theo cách có thể bị thao túng.
Cuộc gọi API backend của bạn sẽ sử dụng một mã thông báo xác thực GraphQL bí mật, khác với mã thông báo công khai mà bạn sử dụng để xác thực tập lệnh JS Zonos. Mã thông báo này có thể được lấy trong Dashboard -> Settings -> Integrations. Mã thông báo bí mật cần được truyền dưới dạng tiêu đề trong cuộc gọi API của bạn.
Biến thể cartCreate
chấp nhận một danh sách các mặt hàng, mà nên được định dạng theo lược đồ mặt hàng giỏ hàng.
Ví dụ tạo giỏ hàng trên máy chủ
// 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
}
Chúng tôi đề xuất tạo một điểm cuối API trên máy chủ của bạn và sau đó gọi điểm cuối đó từ tích hợp JS phía frontend của bạn, điều này sẽ được chi tiết trong bước tiếp theo.
Truyền ID giỏ hàng đến Checkout qua frontend
Khi bạn đã tạo một giỏ hàng trên máy chủ của mình, bạn cần truyền ID giỏ hàng đến tập lệnh JS của Zonos. Điều này có thể được thực hiện bằng cách sử dụng callback createCartId
là một phần của hàm Zonos.init
. Checkout sẽ sau đó an toàn lấy thông tin giỏ hàng từ Zonos khi được mở, ngăn chặn bất kỳ sự can thiệp nào với giỏ hàng.
Zonos JS snippet
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
},
},
});
Tích hợp tùy chỉnh
Xây dựng một tích hợp Checkout hoàn chỉnh vào trang tùy chỉnh của bạn.
Hướng dẫn này đề cập đến các khía cạnh kỹ thuật của việc hoàn thành một tích hợp đầy đủ của Zonos Checkout vào trang hoặc nền tảng tùy chỉnh của bạn. Nó dành cho các nhà phát triển có kinh nghiệm làm việc với JavaScript và có kinh nghiệm phát triển frontend. Tất cả các bước đều cần thiết trừ khi có ghi chú khác.
Điều kiện tiên quyết