💴

【Shopify.dev和訳】Apps/Shopify POS/Cart app extension

2021/09/16に公開約8,300字

この記事について

この記事は、Apps/Shopify POS/Cart app extensionの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

カートアプリ拡張

Shopify のマーチャントはアプリを使って Shopify POS のロイヤリティプログラムや割引を管理することができます。POS カートアプリエクステンションをあなたのアプリに追加することで、マーチャントは Shopify POS の中から迅速かつ簡単にロイヤリティポイントを管理し、カートに直接割引を適用することができます。

必要条件

アプリエクステンションの設定

POS カートアプリの拡張機能は、Partner Dashboard から設定できます。

  1. Partner Dashboard で、Apps をクリックします。
  2. サイドバーの Apps をクリックします。
  3. アプリの名前をクリックします。
  4. Extensions をクリックします。
  5. Point of Sale をクリックします。
  6. POS cart セクションで Manage POS cart をクリックします。
  7. POS カートアプリの拡張機能のエンドポイントを構築するために使用する URL パスを入力します。
  8. Save をクリックします。

たとえば、アプリのベース URL が https://myapp.comで、URL pathpos-extension-api の場合、拡張機能は次のエンドポイントを使用します。

https://myapp.com/pos-extension-api/promotions
https://myapp.com/pos-extension-api/perform_action
https://myapp.com/pos-extension-api/revert_action

エンドポイントの作成

アプリがアプリ拡張機能を通じて Shopify からの通信を受け取る前に、アプリのプライマリドメイン上で一連の標準化された API エンドポイントをホストする必要があります。これらのエンドポイントは、アプリの拡張機能がレンダリングされたときや、アプリから関連するアクションが要求されたときに呼び出されます。

エンドポイントの要件

次の表は、POS カートアプリエクステンションの要件を示しています。

ルール/コンセンサス タイプ/要求事
API 形式 REST
コンテンツタイプ JSON
セキュリティ メカニズム HMAC/Signed リクエスト。API を介して作成された Webhook を検証する方法については、「Webhook」を参照してください。
プロトコル HTTPS (アプリのドメインには有効な SSL 証明書が必要)

リクエストへの応答

全てのエンドポイントは 3 秒以内に応答しなければなりません。そうでない場合、Shopify はコールをタイムアウトさせ、マーチャントにエラーを返します。これは、マーチャントが Shopify POS で遅い体験をするのを防ぐためです。

ベースエンドポイント

あなたのアプリは、POS カートアプリ拡張のための 3 つの API エンドポイントコールをサポートする必要があります。これを行うためには、アプリのベース URL に付加されるパスセグメントを提供し、Shopify によって呼び出される完全な URL を形成する必要があります。これは、パートナーダッシュボードからアプリエクステンションを設定する際に行います。

アプリエクステンションのアーキテクチャ

POS カートアプリエクステンションは、以下の 3 つのエンドポイントに基づいています。

プロモーションのエンドポイント

Shopify POS で新しい注文が開始されたとき(例えば、カートが空になったとき)、またはカート上の顧客が変更されたとき、Shopify はあなたのアプリのプロモーションエンドポイントにリクエストを送ります。このリクエストには、あなたのアプリが Shopify にデータを返すときに使用できる、サポートされているテンプレートとアクションが含まれています。

アプリのレスポンスには、選択されたテンプレート、顧客のロイヤリティポイント、および適用可能なアクションが含まれます。各アクションは、カートに適用可能なプロモーションです。

以下の例では、promotions エンドポイントへのリクエストを示しています。

{
  "shop_id": 1234,
  "customer_id": 5678,
  "supported_templates": ["simple_action_list"],
  "supported_actions": ["flat_discount", "percent_discount", "add_variant"],
  "currency_code": "USD",
  "locale": "en-us"
}

次の例では、テンプレートタイプ、顧客のポイントに関する情報、および適用されるアクションが含まれています。レスポンスのアクションは、お客様の注文に一律 5 ドルの割引を適用します。

{
  "type": "simple_action_list",
  "points_label": "Points balance",
  "points_balance": "23867",
  "actions": [
    {
      "type": "flat_discount",
      "title": "Add $5.00 discount",
      "description": "-1000 points",
      "action_id": "123ABC",
      "value": "5"
    }
  ]
}

次の例では、返されたレスポンスのレンダリング結果を示しています。

perform_action エンドポイント

あなたのアプリがテンプレートとアクションの配列を返した後、Shopify POS は情報をレンダリングし、マーチャントはプロモーションをタップしてカートに適用することができます。実行されたアクションは Shopify に送られ、Shopify はあなたのアプリのperform_actionエンドポイントにアクションをプロキシします。リクエストには、アクションを適切に識別するための action_id フィールドが含まれています。

次の例では、perform_actionエンドポイントへのリクエストを示しています。

{
  "action_id": "123ABC",
  "customer_id": 5678,
  "locale": "en",
  "supported_templates": ["simple_action_list"],
  "supported_actions": ["flat_discount", "percent_discount", "add_variant"],
  "currency_code": "USD",
  "shop_id": 1234
}

次のレスポンス例では、適用された割引に 1000 ポイントかかっているため、points_balance フィールドが「23867」から「22867」に減少しています。この例では、お客様が 1 回の注文で複数のオファーを利用していないため、actions配列は空になっています。

{
  "type": "simple_action_list",
  "points_label": "point balance"
  "points_balance": "22867",
  "actions": []
}

revert_action エンドポイント

アプリの perform_action エンドポイントの呼び出しが成功した後、アクションを元に戻すことができます。例えば、注文が放棄されたり、カートから割引が削除されたりします。これらのケースでは、Shopify は元に戻すアクションの ID を持つアプリの revert_action エンドポイントにリクエストを送信します。

次の例では、revert_action エンドポイントへのリクエストを示しています。

{
  "action_id": "123ABC",
  "customer_id": 5678,
  "locale": "en",
  "supported_templates": ["simple_action_list"],
  "supported_actions": ["flat_discount", "percent_discount", "add_variant"],
  "currency_code": "USD",
  "shop_id": 1234
}

次のレスポンス例では、割引アクションが元に戻された後、ポイント残高が元の値「23867」に増加し、お客様が再び割引アクションを利用できるようになっています。

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "23867",
  "actions": [
    {
      "type": "flat_discount",
      "title": "Add $5.00 discount",
      "description": "-1000 points",
      "action_id": "123ABC",
      "value": "5.00"
    }
  ]
}

検証の実施

Shopify によるアプリ拡張リクエストは、デジタル署名を計算することで検証できます。

各リクエストには base64 エンコードされた X-Shopify-HMAC-SHA256 ヘッダーが含まれており、リクエストで送信されたデータと共にアプリの共有シークレットを使用して生成されます。

リクエストが Shopify から来たものであることを確認するには、HMAC ダイジェストを計算し、それを X-Shopify-HMAC-SHA256 ヘッダーの値と比較します。それらが一致すれば、アプリ拡張リクエストが Shopify から送信されたことを確認できます。

詳しくは Webhooks を参照して、API を通して作成された Webhook を確認する方法を学んでください。これは、アプリの拡張機能についても同じ手順です。

次のステップ

POS カートのアプリ拡張の各エンドポイント呼び出しのために Shopify があなたのアプリに送信するフィールドと、あなたのアプリが Shopify に送信するテンプレートとアクションのレスポンスフィールドと可能な値について学びます。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます