新しい購入や無料トライアルの処理

お客様が有料プラン、無料試用版、または GitHub Marketplace アプリの無料バージョンを購入すると、イベント Webhook が送信され、marketplace_purchase が含まれ、購入プロセスが開始されます。

この記事で

メモ

この記事は、GitHub Marketplace でのアプリの公開にのみ適用されます。 GitHub Marketplace での GitHub Actions の公開について詳しくは、「GitHub Marketplaceでのアクションの公開」をご覧ください。

警告

GitHub MarketplaceでGitHub Appを提供している場合、アプリケーションはOAuthの認可フローに従ってユーザを識別しなければなりません。 このフローをサポートするために、別のOAuth appを設定する必要はありません。 詳細については、「ユーザーに代わってGitHub アプリで認証する」を参照してください。

ステップ 1. 初回購入とWebhookイベント

顧客は GitHub Marketplace アプリを購入する前に、登録情報プランを選択します。 顧客は、アプリケーションの購入を自分の個人アカウントから行うのか、あるいはOrganizationアカウントから行うのかも選択します。

          **[注文を完了してインストール開始]** をクリックすることで、顧客は購入を完了します。

その後、GitHub は、marketplace_purchase Webhook と purchased アクションをアプリに送信します。

          `effective_date` webhook からの `marketplace_purchase` および `marketplace_purchase` オブジェクトを読み取って、顧客が購入したプラン、請求サイクルの開始時期、および次の請求サイクルの開始時期を特定します。

アプリで無料試用版が提供されている場合は、webhook から marketplace_purchase[on_free_trial] 属性を読み取ってください。 値が true である場合、アプリは無料試用版の開始日 (effective_date) と無料試用版の終了日 (free_trial_ends_on) を追跡する必要があります。 アプリケーションの UI に無料トライアルの残日数を表示するのには、free_trial_ends_on の日付を使ってください。 これは、バナーか支払い UI のどちらかで行うことができます。 無料試用版が終了する前にキャンセルを処理する方法については、「プランのキャンセルの処理」を参照してください。 無料試用版の有効期限が切れたときに無料試用版を有料プランに移行する方法については、「プラン変更の処理」を参照してください。

marketplace_purchase イベント ペイロードの例については、「GitHub Marketplace API の Webhook イベント」を参照してください。

手順 2. インストール

アプリが GitHub App である場合、GitHub は顧客に対してアプリの購入時にそのアプリがアクセスできるリポジトリの選択を求めます。 GitHub は、顧客が選んだアカウントにアプリをインストールして、選択されたリポジトリへのアクセスを許可します。

GitHub App の設定でセットアップ URL を指定してある場合、この時点で、GitHub は顧客をその URL にリダイレクトします。 Setup URLを指定していない場合、GitHub Appの購入を処理することはできません

メモ

          **[Setup URL]** は、GitHub App の設定では省略可能とされていますが、アプリを GitHub Marketplace で提供したい場合は必須のフィールドです。 詳しくは、「[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/about-the-setup-url)」をご覧ください。

アプリが OAuth app である場合、GitHub はそれをどこにもインストールしません。 代わりに、GitHub は、GitHub Marketplace のリストで指定されているインストール URL に、顧客をリダイレクトします。

顧客が OAuth app を購入すると、GitHub は顧客を選択されている URL (セットアップ URL またはインストール URL) にリダイレクトし、その URL のクエリ パラメーター marketplace_listing_plan_id には顧客が選んだ価格プランが含まれます。

手順 3. 許可

顧客がアプリケーションを購入したら、顧客をOAuthの認可フローに送らなければなりません。

  • アプリが GitHub App である場合は、GitHub が顧客をセットアップ URL にリダイレクトするとすぐに、認可フローが開始されます。 「ユーザーに代わってGitHub アプリで認証する」の手順に従います。

  • アプリが OAuth app である場合は、GitHub が顧客をインストール URL にリダイレクトするとすぐに、認可フローが開始されます。 「OAuth アプリの承認」の手順に従います。

どちらの種類のアプリでも、最初の手順は顧客を https://github.com/login/oauth/authorize にリダイレクトすることです。

顧客が認可を完了すると、アプリケーションは顧客のOAuthアクセストークンを受け取ります。 このトークンは、次のステップで必要になります。

メモ

顧客を無料トライアルで認可する場合は、有料プランの場合と同じアクセス権を付与してください。 それらの顧客は、無料の期間が終了したら有料プランに移行させます。

手順 4. 顧客アカウントの設定

アプリケーションは、すべての新規購入に対して顧客アカウントをプロビジョニングしなければなりません。 その顧客に対して受け取ったアクセス トークン (「ステップ 3. 認可」を使って GET /user/marketplace_purchases エンドポイントを呼び出します。 応答には顧客の account 情報が含まれ、無料試用版 (on_free_trial) に含まれているかどうかが示されます。 この情報を使って、セットアップとプロビジョニングを完了させてください。

メモ

GitHub Marketplace の現在のバージョンでは、お客様がアプリの Web サイトで購入したアカウントを既にお持ちの場合、GitHub Marketplace からアプリを購入できます。 アプリを購入した顧客のアカウントが既に設定されている場合は、"二重" 購入を GitHub Support に報告してください。

購入がOrganizationのためのものであり、ユーザごとであるなら、顧客に対して購入されたアプリケーションにアクセスできるOrganizationのメンバーの選択を求めることができます。

Organizationのメンバーがアプリケーションへのアクセスを受け取る方法は、カスタマイズできます。 いくつかの推奨事項を次に示します。

          **定額料金:** 組織に対して定額料金での購入が行われたなら、アプリケーションは API 経由で [組織の全メンバーを取得](/rest/orgs/members#list-organization-members)して、組織の管理者に対してどのメンバーがインテグレーター側で有料ユーザとなるかの選択を求めることができます。

          **ユニット単位の料金:** ユニット シートごとにプロビジョニングする方法の 1 つは、ユーザーがアプリケーションにログインしたときにシートを使用できるようにすることです。 顧客がシートカウントの閾値に達した場合、アプリケーションはユーザに対してGitHub Marketplaceを通じてアップグレードする必要があることを警告できます。