Checkout•

主页全球电子商务集成集成 Checkout 定制集成

定制集成

在您的定制网站中构建端到端Checkout集成。

本指南涵盖将Zonos Checkout完整集成到您的定制网站或平台的技术方面。它旨在为熟悉JavaScript并具有前端开发经验的开发人员提供指导。除非另有说明，所有步骤都是必需的。

先决条件

注册一个Zonos账户

完成您的账户设置

自定义您的品牌设置

安装Zonos JS脚本

您的定制集成需要包含Zonos JavaScript代码片段。该脚本负责渲染Checkout用户界面、Zonos Hello、处理支付处理和访客地理IP检测。

安装Zonos JS代码片段

Zonos Elements脚本可在以下URL获取：

Zonos JS代码片段

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

处理浏览器缓存

我们通常建议在 URL 后附加时间戳或其他唯一标识符，以确保脚本不会被浏览器缓存。这将确保始终加载脚本的最新版本。例如：

Zonos JS snippet

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

验证 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 需要了解额外的商品信息，例如名称和描述，以及“添加到购物车”按钮。您可以将 CSS 选择器传递给 Hello，以便它能够从页面中抓取这些信息。

Zonos JS 代码片段

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

可选 — 在页面加载时自动打开 Hello

默认情况下，Hello 仅在访客点击旗帜按钮时打开。如果您希望在页面加载时自动打开 Hello，可以在 Zonos 脚本加载后调用 Zonos.openHelloDialog() 函数。

Zonos JS 代码片段

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

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

传递购物车只读购物车详情到 Checkout

buildCartDetail 回调负责以 Checkout 接口可以理解和显示的格式返回购物车详情。此函数在客户到达 checkout 页面时立即调用，确保购物车详情在 Checkout 的第一页上准确显示。请注意，这不用于计算 - 这将在下一步中处理。

Zonos JS 代码片段

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

购物车项目架构

buildCartDetail 函数应返回一个购物车项目的数组。以下是每个 CartItem 对象结构的详细表格：

字段名称	类型	必需	描述
`amount`	数字	是	项目的价格金额。
`countryOfOrigin`	字符串	否	项目的原产国。
`currencyCode`	字符串	是	金额的货币代码。
`description`	字符串	否	项目的描述。
`hsCode`	字符串	否	项目的协调系统代码。
`imageUrl`	字符串	否	项目图像的 URL。
`measurements`	ItemMeasurement[]	否	项目测量的数组。
`metadata`	对象（字符串/数字对）	否	关于项目的附加元数据。
`name`	字符串	是	项目的名称。
`productId`	字符串	否	产品 ID。
`quantity`	数字	是	购物车中项目的数量。
`sku`	字符串	否	库存单位标识符。

安全地将 landed cost 传递给 Checkout

buildLandedCost 函数负责安全地计算 landed cost。在客户输入其运输信息后调用此函数。该函数计算运费和其他必要费用，然后在 Checkout 的后续页面上显示。

重要的是，您必须在服务器端处理 landed cost 计算逻辑，因为这是确保购物车详细信息不暴露给客户浏览器的唯一方法。如果您使用无服务器架构，可以使用无服务器函数来处理 landed cost 计算。buildLandedCost 函数应简单地调用无服务器函数/API 端点并返回结果。

在服务器端，您可以使用 Zonos Checkout API 通过以下 POST 请求计算 landed cost。您需要在 credentialToken 头中传递您一直在使用的 Zonos JS 脚本的 API 密钥。

请求 URL

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 JS 代码片段

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // This should return the landed cost calculation
    },
  },
});

这个页面有帮助吗？

有问题吗？

联系我们。

查 Zonos

政策和协议