安装Zonos JS脚本
您的定制集成需要包含Zonos JavaScript代码片段。该脚本负责渲染Checkout用户界面、Zonos Hello、处理支付处理和访客地理IP检测。
安装Zonos JS代码片段
Zonos Elements脚本可在以下URL获取：
Zonos JS代码片段
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />
处理浏览器缓存
我们通常建议在 URL 后附加时间戳或其他唯一标识符，以确保脚本不会被浏览器缓存。这将确保始终加载脚本的最新版本。例如：
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>
验证 Zonos JS 代码片段
一旦加载了 Zonos JS 脚本，您需要通过将 Zonos API 密钥 和商店 ID 传递给 Zonos.init 函数来进行验证。用于验证 Checkout 的 API 密钥设计为可发布的，这意味着它们可以安全地用于前端代码，而不会暴露任何敏感信息。
Zonos JS 代码片段
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
});
设置允许的域名
为了确保 Zonos JS 脚本仅在允许的网站上加载，我们根据“允许的域名”列表过滤请求。该列表在仪表板中配置。如果没有此配置，Zonos JS 脚本将返回权限错误，而不是正常加载。
要更新您的允许域名：
- 转到 仪表板 -> 设置 -> Checkout 设置。
- 在 允许的域名 部分，添加您将集成 Checkout 的域名。
- 点击 保存。
设置 Zonos Hello
一旦您设置了 Zonos JS 脚本，您需要配置 Hello 以与您的网站配合使用。Hello 负责检测访问者的位置、语言和货币，并向他们显示适当的信息。使用 Hello 时需要 Checkout。
您可以在仪表板和 Hello JS 脚本中配置所有 Zonos 设置。如果您已经在仪表板中配置了 Hello，脚本将加载这些设置并使用它们。如果您在 Zonos.init 函数的 helloSettings 属性中指定任何值，脚本将使用这些值。
配置货币转换
Hello 使用 CSS 选择器来识别您网站上显示货币信息的元素。您需要将这些选择器传递给 Zonos.init 函数的 helloSettings.currencyElementSelector 属性。
您可以在这里使用任何 有效的 CSS 选择器，例如 #price, .price 来选择多个不同的元素。
Zonos JS 代码片段
Zonos.init({
// ... other fields
helloSettings: {
// ... other fields
currencyElementSelector: '#price, .price', // Replace with your actual selector
},
});
可选 — 在页面加载时自动打开 Hello
默认情况下，Hello 仅在访客点击旗帜按钮时打开。如果您希望在页面加载时自动打开 Hello，可以在 Zonos 脚本加载后调用 Zonos.openHelloDialog() 函数。
Zonos JS 代码片段
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
设置 Zonos Checkout
一旦 Hello 被配置好，您需要设置 Checkout 以便与您的网站配合使用。 Checkout 负责让客户输入他们的运输信息，计算 landed cost，并完成订单。
Checkout 将与 Hello 共享上下文数据，例如访问者的位置、语言和货币。这确保了客户在整个购物过程中体验的一致性。
您可以在 Dashboard 和 Checkout JS 脚本中配置所有 Zonos 设置。如果您已经在 Dashboard 中配置了 Checkout，脚本将加载这些设置并使用它们。如果您在 Zonos.init 函数的 checkoutSettings 属性中指定了任何值，脚本将使用这些值。
配置“下订单”按钮
Zonos JS 脚本将自动识别国际购物者并将他们引导到 Checkout 流程。然而，您需要在您的平台上配置“下订单”按钮，以便在点击时打开 Checkout。这可以通过将 CSS 选择器传递给 Zonos.init 函数的 checkoutSettings.placeOrderButtonSelector 属性来完成。
如果您有多个按钮可以用于下订单，请确保传递一个可以匹配所有按钮的选择器。例如，#placeOrder, .place-order 将匹配 #placeOrder 和 .place-order。
Zonos JS snippet
Zonos.init({
// ... other fields
checkoutSettings: {
// ... other fields
placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
},
});
安全地在服务器端创建购物车详情
为了向客户显示购物车详情，您需要创建一个服务器端函数，该函数将调用Zonos API 来创建购物车，然后将该购物车 ID 传回前端。这将确保购物车详情不会以可被操控的方式暴露给客户。
您的后端 API 调用将使用一个秘密的 GraphQL 凭证令牌，该令牌与您用于验证Zonos JS 脚本的公共令牌不同。该令牌可以在 Dashboard -> Settings -> Integrations 中获取。秘密令牌需要作为头部传递在您的 API 调用中。
cartCreate 变更接受一个项目列表，该列表应根据 购物车项目架构 格式化。
示例服务器端购物车创建
// 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
}
我们建议在您的服务器端创建一个 API 端点，然后从您的前端 JS 集成中调用该端点，详细信息将在下一步中说明。
通过前端将购物车 ID 传递给 Checkout
一旦您在服务器端创建了购物车，您需要将购物车 ID 传递给 Zonos JS 脚本。这可以通过使用 createCartId 回调来完成，该回调是 Zonos.init 函数的一部分。Checkout 将在打开时安全地从 Zonos 检索购物车详细信息，从而防止对购物车的任何篡改。
Zonos JS 代码片段
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
},
},
});
定制集成
在您的定制网站中构建端到端Checkout集成。
本指南涵盖将Zonos Checkout完整集成到您的定制网站或平台的技术方面。它旨在为熟悉JavaScript并具有前端开发经验的开发人员提供支持。除非另有说明，所有步骤都是必需的。
先决条件