Checkout•

カスタム統合

カスタムサイトにエンドツーエンドのCheckout統合を構築します。

このガイドでは、Zonos Checkoutをカスタムサイトまたはプラットフォームに完全に統合するための技術的な側面を説明します。JavaScriptを使いこなし、フロントエンド開発の経験がある開発者を対象としています。特に記載がない限り、すべてのステップが必要です。

前提条件

Zonosアカウントにサインアップ

アカウント設定を完了する

ブランド設定をカスタマイズする

Zonos JSスクリプトのインストール

カスタム統合にはZonosのJavaScriptスニペットを含める必要があります。このスクリプトは、Checkout UIのレンダリング、Zonos Hello、支払い処理、訪問者のGeo-IP検出を担当します。

Zonos JSスニペットのインストール

Zonos Elementsスクリプトは、以下のURLで入手できます：

Zonos JSスニペット

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

ブラウザキャッシュの処理

通常、ブラウザによってスクリプトがキャッシュされないように、URLにタイムスタンプやその他のユニークな識別子を追加することをお勧めします。これにより、常に最新のバージョンのスクリプトが読み込まれます。例えば：

Zonos JS スニペット

<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 設定は、ダッシュボードと Zonos JS スクリプトの両方で構成できます。すでにダッシュボードで 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 にCSSセレクタを渡すことで、ページからこの情報をスクレイピングできるようになります。

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と共有します。これにより、顧客の体験がショッピングプロセス全体で一貫性を保つことができます。

すべてのCheckout設定は、DashboardとZonos JSスクリプトの両方で構成できます。すでにDashboardでCheckoutを設定している場合、スクリプトはそれらの設定を読み込み、使用します。Zonos.init関数のcheckoutSettingsプロパティに値を指定した場合、スクリプトはそれらの値を代わりに使用します。

'注文を確定する'ボタンの設定

Zonos JSスクリプトは、国際的なショッパーを自動的に認識し、Checkoutフローに誘導します。ただし、クリック時にCheckoutを開くように、プラットフォーム上の'注文を確定する'ボタンを設定する必要があります。これは、Zonos.init関数のcheckoutSettings.placeOrderButtonSelectorプロパティにCSSセレクタを渡すことで行えます。

複数のボタンが注文を確定するために使用できる場合は、すべてのボタンに一致するセレクタを渡すようにしてください。たとえば、#placeOrder, .place-orderは、#placeOrderと.place-orderの両方に一致します。

Zonos JSスニペット

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を見る

ポリシーと契約