【Shopify.dev和訳】Apps/Channels/Onboarding & account connection

この記事について

この記事は、Apps/Channels/Onboarding and account connectionの記事を和訳したものです。

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

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

販売チャネルのオンボーディングとアカウント接続フローを構築する

このガイドでは、OAuth と Shopify の Polaris コンポーネントを使用して、マーチャントをオンボーディングしてチャネルに接続する方法について説明します。

前提条件

このガイドは、あなたが以下に精通していることを前提としています。

• Building Shopify channels
• Get started building a sales channel

オンボーディングとアカウント接続

OAuth を使用して、販売チャネルアプリをインストールする許可をマーチャントから取得します。マーチャントはアプリをインストールするためのリンクをクリックすると、Shopify の OAuth 画面にリダイレクトされます。

マーチャントが OAuth パーミッションに同意した後、アプリはアクセストークンを要求し、API アクセスに使用します。マーチャントは Shopify にリダイレクトされ、アプリのオンボーディングフローが完了します。

ステップ 1: Shopify のセットアップ

アプリから API にアクセスするために、Shopify のライブラリをインストールします。

ステップ 2: アプリの URL をホストする

ユーザーがアプリに権限を与えることができるように、サーバー上に OAuth アプリの URL をホストします。

https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={access_mode}

アプリの URL プロパティの定義については、「OAuth による認証」を参照してください。

権限

販売チャネルアプリには、以下の OAuth アクセススコープをリクエストできます。

• read_product_listings
• write_checkouts

セールスチャネルアプリは、自分自身の注文のみを読むことができます。つまり、あなたのアプリは、あなたのチャネルに帰属する売上の注文のみを読むことができます。

詳細については、「OAuth での認証」を参照してください。

ステップ 3: ショップのトークンを取得する

コードをトークンに交換することで、ショップのトークンを取得できます。アクセストークンと交換できるコードを含む、次のリダイレクト URL がアプリサーバーに返されます。

https://example.org/some/redirect/uri?code={authorization_code}&hmac=da9d83c171400a41f8db91a950508985&timestamp=1409617544&state={nonce}&shop={hostname}

URI からパラメータを抽出し、サーバーに保存した状態と照合するハンドラを書き、トークンを Shopify の API に送信します。

返されたトークンはデータベースに保存することができます。これはマーチャントアカウントの識別子であり、マーチャントに代わって Shopify と通信するために使用することができます。

Tip
組み込みアプリで OAuth を実行する場合、最初の OAuth リクエストリダイレクトは iframe をエスケープする必要があります。詳細については、Embedded AppSDK 入門を参照してください。

ステップ 4: Shopify のアプリのオンボーディングにユーザーをリダイレクトする

ユーザーを Shopify のアプリのアカウントページにリダイレクトする必要があります。Shopify にアプリを埋め込むには、Shopify App Bridge または EASDK を使用する必要があります。Shopify Polaris の Empty state コンポーネントを使用して、値の記述、イラスト、アカウント接続コンポーネントのボタンをホストする画面を構築する必要があります。

デフォルトでは、あなたのアプリの最初のオンボーディング画面は、以下のように見えるかもしれません。

ステップ 5: アカウント接続フォームのスタイルを設定する

Polaris のアカウント接続コンポーネントを使用して、マーチャントをあなたのチャンネルに接続する必要があります。フォームには御社のブランドを反映させる必要があります。これにより、マーチャントが貴社のアカウントに接続していることを明確に伝え、信頼を築くことができます。マーチャントがオンボーディングに関する質問をする際に、誰に連絡すればよいかを明確にする必要があります。

コンポーネントの例を参照して、ユーザーの視点からアカウント接続を確認してください。

例えば、アカウント接続フォームは以下のようになります。

ステップ 6: 適格なステップまたは追加のオンボーディング要件のセットアップフローを含める

対象となるステップ、資格要件、または追加のオンボーディング要件がある場合は、これらをアカウント接続フォームに記載する必要があります。また、ここでアプリの利用規約（TOS）を表示することができます。Shopify では、オンボーディングプロセスをシンプルに保つために、セットアップフローを最大 3 ～ 4 の個別ステップにすることを推奨しています。一般的に含まれるトピックは、製品カテゴリーとフルフィルメントオプションです。例えば、マーケットプレイスアプリを構築しているのであれば、このフローの一部としてフルフィルメントオプションや注文管理に関する期待事項を伝えることができます。また、マーチャントの支払い情報を収集し、マーケットプレイスでの売上に応じてマーチャントに支払いを行う場合にも適しています。どのようなタイプの販売チャネルアプリを構築しているかにかかわらず、アプリの価格や手数料については明確に、かつ率直に説明する必要があります。アプリがチェックアウト API を使用する場合は、AppSubscription リソースを使用して、マーチャントに定期的な課金に同意するよう促す必要があります。詳細については、「支払いを受ける」を参照してください。

追加のステップは、以下のようになります。

アカウントセクション

マーチャントがアカウント接続とオンボーディングを完了した後、Shopify のアプリのアカウントページにリダイレクトされます。

アカウントページの作成

レイアウトコンポーネントを使用して、アカウントページを構築する必要があります。レイアウトコンポーネントで構築されたページには、コンテキストエリア（カードの左側、デスクトップ）と機能エリア（カード、メイン/右側、デスクトップ）があります。機能エリアは card コンポーネントを使用して構築されます。

アカウントページは、左にコンテキストエリア、右に機能エリアを配置した以下のようなものになります。

コンテキストエリア

各セクションのタイトルと説明は、マーチャントがあなたの販売チャネルで意思決定を行うために必要なコンテキストを与えるために使用されます。

セクションの見出し: マーチャントはこのセクションでどのような情報、機能を扱うのでしょうか？簡潔に、可能であれば「在庫管理」のように自社プラットフォームの用語を使用してください。

説明文: なぜこの情報や機能が重要なのか、それがマーチャントにどのようなメリットをもたらすのかを 1 センテンスで説明します。また、「Learn more about [feature name]」のように、お客様のプラットフォームのサイトにあるドキュメントや詳細情報を示すテキストリンクを含めることもできます。

アカウントレビュー（任意のステップ

販売チャネルにレビュープロセスがある場合は、Banner コンポーネントを使用してアカウントステータス情報をマーチャントに伝えることができます。

アプリにレビュープロセスがある場合は、青いバナーコンポーネントを使用してこの情報を伝えることができます。

アカウントレビューのメッセージは以下のようになります。

アカウント接続成功

マーチャントが審査プロセスを正常に通過した場合は、緑色のバナーコンポーネントを使用して成功を示すことができます。

アカウントの拒否

販売者がレビュープロセスに失敗した場合は、赤いバナーコンポーネントを使用してこれを示すことができます。

アカウントの切断

販売チャネルは、アカウントセクションからチャネルから切断するオプションをマーチャントに提供する必要があります。このアクションは元に戻せないため、切断をクリックすると、赤いボタンを備えたハードアラートを起動する必要があります。

コミッション

アプリには、card コンポーネントと注釈付きレイアウトを使用して、コミッションセクションを含める必要があります。コミッションセクションには、コミッションレートと、マーチャントへの請求方法および請求時期を記載する必要があります。

利用規約

アプリには、利用規約セクションを含める必要があります。このセクションのリンクは、新しいウィンドウで開く必要があります。ご利用規約は、販売チャネルアプリの外部でホストされますが、ご利用規約モジュールからリンクされます。モジュールは、アカウント接続後に表示され、「アカウント」ページの下部に配置する必要があります。

ヘルプフッター

ヘルプフッターは、販売チャネルのすべてのページに表示する必要があります。これは、セールスチャネルのドキュメントやサポートへのリンクをユーザーに提供する便利な方法です。

商品の公開

マーチャントが承認された後、マーチャントの製品を販売チャネルに公開することができます。このプロセスでは、フロントエンドとバックエンドの両方を考慮する必要があります。

ステップ 1: 商品公開の管理

バックエンド

デフォルトでは、すべての利用可能な製品はあなたのチャネルに公開することができます。しかし、Shopify では、マーチャントが商品の表示場所をコントロールする方法に合わせて、代わりに ProductListing リソースから商品カタログを読み取ることを推奨しています。

以下のように Shopify API を呼び出して、製品リストを取得することができます。

GET https://{shop}.myshopify.com/admin/api/2021-07/product_listings.json

応答として、API は JSON としてフォーマットされた製品リストを返します。

どの商品をアプリに公開するかをコントロールしたい場合は、このリソースに PUT リクエストを送信して、マーチャントに代わって商品を公開することができます。

また、GraphQL Admin API で一括操作を行うことで、商品を一括で読み込むこともできます。

フロントエンド

商品の公開状況をマーチャントに伝えるためには、card コンポーネントを使ってステータスカードを作成する必要があります。このステータス・セクションは、アカウント・セクションの一部として含まれます。ステータスセクションには、公開された製品の数が表示されます。チャネルへの公開に失敗した製品がある場合、マーチャントには、パブリッシングステータスカードにエラーが発生した製品の数が明確に表示されます。マーチャントは、ステータスカードに記載されているリンクにアクセスすることで、パブリッシングエラーのあるすべての製品をチャネルから直接見ることができます。

ステータスカードは以下のようになっています。

ステップ 2: 商品情報の管理

場合によっては、チャンネルに必要なすべての製品情報が製品カタログから得られないことがあります。そのような場合は、メタフィールドを使用して追加情報を取得することができます。また、同じ目的で使用できるMetafieldリソースもあります。

フロントエンド

フロントエンドでは、Shopify の商品ページにある「その他のアクション」ドロップダウンの下にメタフィールドが表示されます。

例として、メタフィールドを実装するために使用されたパターンの例を示します。

追加のフィールドは、「More actions」ドロップダウンを使用して表示されます。

マーチャントは、Shopify の「商品」セクションにアクセスして、販売チャネルに公開されている商品を表示し、管理することができます。商品セクションから、マーチャントは 1 つずつ、またはバルクエディタを使用して、パブリッシングエラーを解決することができます。

ステップ 3: エラーの管理

マーチャントの製品カタログを販売チャネルに公開しようとすると、エラーが発生する場合があります。この場合、これらのエラーを解決するために、さまざまな対策を講じることができます。

フロントエンド

マーチャントに製品公開エラーを表示するには、card コンポーネントを使用してステータスカードを構築する必要があります。このステータスセクションは、チャネルアカウントページの一部として含まれています。

ステータスカードには、同期中の商品や、同期を妨げるエラーが発生した商品を表示することができます。

販売者は、商品公開カードにあるリンクにアクセスして、チャネルから直接公開エラーのあるすべての商品を表示できるようにする必要があります。すべてのエラーが解決されたら、成功バナーを表示できます。

リソースフィードバック

リソースフィードバック API は、マーチャントにエラー解決を促すための仕組みを提供します。これは、商品が公開に適していない場合や、以前に公開した商品を編集した際にエラーが発生した場合など、さまざまな場面で役立ちます。

チャネルが必要とする商品の属性に欠けているものがあれば、リソースフィードバック API を使って「商品」ページにリストアップすることができます。商品リソースのフィードバックは、「商品」ページの「商品の有無」セクションのチャネル名の下にマーチャントに表示されます。

製品リソースフィードバック:

製品レベルのリソースフィードバックは、製品とそのバリエーションに関わるすべてのものに使用できます。

商品リソースフィードバックを作成するために、Shopify API に以下の呼び出しを行うことができます。

POST https://{shop}.myshopify.com/admin/api/2021-07/products/#{product_id}/resource_feedback.json

リソースフィードバックを作成した後は、商品の更新を受けた際に、その商品の有効性を確認する必要があります。エラーが解消されていれば、リソースフィードバックを解除することができます。

ショップのリソースフィードバック:

カタログ全体に影響するアカウントレベルのエラーには、Shop レベルのフィードバックを使用できます。

リソースフィードバックを作成するには、Shopify API に以下の呼び出しを行います。

POST https://{shop}.myshopify.com/admin/api/2021-07/resource_feedback.json

ステップ 4: 商品の変更に同期する

商品がチャンネルに公開され、エラーがあれば対処した後、Shopify での変更に合わせて商品カタログを最新の状態に保つ必要があります。例えば、マーチャントは商品のタイトルや画像を変更したり、商品を在庫切れにしたりすることができます。変更の通知を受けるためには、商品または商品リストレベルの webhook を購読することができます。

• product_listings/add
• product_listings/update
• product_listings/remove
• collection_listings/add
• collection_listings/update
• collection_listings/remove

リクエストの本文にトピックを指定することで、API を使って Webhook を設定することができます。

次の例では、product_listings/add webhook を使用するリクエストを示しています。

POST /admin/api/2020-01/webhooks.json HTTP/1.1
Host: channelsrule.myshopify.com
X-Shopify-Access-Token: 085abas8bd90325c3f81s8e9c88befc0
Content-Type: application/json

{
    "webhook": {
        "topic": "product_listings/add",
        "address": "https://yourchannelapp.com/webhooks",
        "format": "json",
    }
}

API 呼び出しは、次の応答を返します。

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
X-Shopify-Shop-Api-Call-Limit: 1/40

{
    "webhook": {
        "id": 125777732,
        "address": "https://yourchannelapp.com/webhooks",
        "topic": "product_listings/add",
        "created_at": "2015-12-08T06:16:53+01:00",
        "updated_at": "2015-12-08T06:16:53+01:00",
        "format": "json",
        "fields": [],
        "metafield_namespaces": []
    }
}

次に、サーバー上に HTTP エンドポイントを作成して、イベントを監視できます。詳細については、Webhook のエンドポイントの作成を参照してください。

Tip
Webhooks の HMAC 検証は、OAuth の検証/妥当性とは異なることに注意してください。詳しくは、「webhooks を設定する」を参照してください。

次のステップ

• Build a sales channel with the Checkout API
• Build a sales channel with cart permalinks

さらに詳しい情報

• 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