Zonos JSスクリプトをインストールする
カスタム統合にはZonosのJavaScriptスニペットを含める必要があります。このスクリプトは、Checkout UIのレンダリング、Zonos Hello、支払い処理の管理、訪問者のGeo-IP検出を担当します。
Zonos JSスニペットをインストールする
Zonos Elementsスクリプトは、以下のURLで入手できます：
Zonos JSスニペット
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />
ブラウザキャッシュの処理
通常、ブラウザによってスクリプトがキャッシュされないように、URLにタイムスタンプやその他のユニークな識別子を追加することをお勧めします。これにより、常に最新のバージョンのスクリプトが読み込まれることが保証されます。例えば：
Zonos JS スニペット
<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 設定は、ダッシュボードと Zonos JS スクリプトの両方で構成できます。すでにダッシュボードで Hello を設定している場合、スクリプトはそれらの設定を読み込み、使用します。Zonos.init 関数の helloSettings プロパティに値を指定した場合、スクリプトはそれらの値を代わりに使用します。
通貨変換の設定
Hello は、サイト上の通貨情報を表示する要素を特定するために CSS セレクタを使用します。これらのセレクタを Zonos.init 関数の helloSettings.currencyElementSelector プロパティに渡す必要があります。
ここでは、例えば #price, .price のように、複数の異なる要素を選択するために任意の 有効な CSS セレクタ を使用できます。
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と共有します。これにより、顧客の体験がショッピングプロセス全体で一貫性を保つことができます。
すべての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)
},
});
サーバーサイドでカートの詳細を安全に作成する
顧客にカートの詳細を表示するためには、Zonos APIを呼び出してカートを作成し、そのカートIDをフロントエンドに返すサーバーサイドの関数を作成する必要があります。これにより、カートの詳細が顧客に操作可能な形で公開されることを防ぎます。
バックエンドのAPI呼び出しでは、Zonos JSスクリプトを認証するために使用する公開トークンとは異なる秘密のGraphQL認証トークンを使用します。このトークンは、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統合から呼び出すことをお勧めします。これは次のステップで詳しく説明します。
フロントエンド経由でCheckoutにカートIDを渡す
サーバーサイドでカートを作成したら、カート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を使いこなし、フロントエンド開発の経験がある開発者を対象としています。特に記載がない限り、すべてのステップが必要です。
前提条件