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

お客様が有料プラン、無料試用版、または GitHub Marketplace アプリの無料バージョンを購入すると、purchased アクションを含む marketplace_purchase イベント Webhook を受け取り、購入フローが開始されます。

この記事の内容

注: この記事は、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 アクションでアプリに送信します。

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の設定で Setup URL を指定している場合、GitHub は顧客をその URL へリダイレクトさせます。 Setup URLを指定していない場合、GitHub Appの購入を処理することはできません

注: Setup URL は、GitHub App の設定中でオプションとされていますが、アプリケーションを GitHub Marketplace で提供したい場合には必須のフィールドです。 詳しくは、「セットアップ URL について」を参照してください。

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

顧客が OAuth app を購入すると、GitHub によって顧客は選択された URL (Setup URL または Installation URL) にリダイレクトされ、その URL には顧客が選択した価格プランがクエリ パラメータの marketplace_listing_plan_id として含まれます。

手順 3. 承認

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

  • アプリケーションが GitHub App である場合、GitHub が顧客を Setup URL にリダイレクトした後すぐに認可フローを始めます。 「ユーザーに代わって GitHub アプリで認証する」の手順に従います。

  • アプリケーションが OAuth app である場合、GitHub が顧客を Installation 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 経由で 組織の全メンバーを取得して、組織の管理者に対してどのメンバーがインテグレーター側で有料ユーザとなるかの選択を求めることができます。

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