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

ステップ 1. 最初の購入とwebhookイベント

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

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

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

marketplace_purchase webhook からの effective_date および 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の購入を処理することはできません

アプリが 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) に含まれているかどうかが示されます。 この情報を使って、セットアップとプロビジョニングを完了させてください。

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

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

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

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