ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

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

顧客が有料プラン、無料のトライアル、あるいはGitHub Marketplaceアプリケーションの無料バージョンを購入した場合、purchasedアクションが付いたmarketplace_purchaseイベント webhookを受信することになり、それによって購入フローが開始されます。

ここには以下の内容があります:

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

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

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

Complete order and begin installation(注文を完了してインストールを開始)をクリックすることで、顧客は購入を完了します。

そうすると、GitHubはmarketplace_purchase webhookにpurchasedアクションを付けてアプリケーションに送信します。

marketplace_purchase webhookからeffective_datemarketplace_purchaseを読み取り、顧客が購入したプラン、支払いサイクルの開始時点、次の支払いサイクルの開始時点を判断してください。

アプリケーションが無料トライアルを提供しているなら、webhookからmarketplace_purchase[on_free_trial]属性を読んでください。 この値がtrueなら、アプリケーションは無料トライアルの開始日(effective_date)と、無料トライアルの終了日(free_trial_ends_on)を追跡しなければなりません。 アプリケーションのUIに無料トライアルの残日数を表示するのには、free_trial_ends_onの日付を使ってください。 これはバナーか、支払いUIのいずれでも行えます。 無料トライアルの終了前のキャンセルの処理方法を学ぶには、「プランのキャンセル」を参照してください。 無料トライアルの終了時点での無料トライアルから有料プランへの移行方法を知るには、「プランのアップグレードとダウングレード」を参照してください。

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

ステップ 2. インストール

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

この時点で、GitHub Appの設定でSetup URLを指定しているなら、GitHubは顧客をそのURLへリダイレクトさせます。 Setup URLを指定していないなら、GitHub Appの購入を処理することはできません

ノート: Setup URLはGitHub Appの設定中でオプションとされていますが、アプリケーションをGitHub Marketplaceで提供したい場合には必須のフィールドです。

アプリケーションが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 Appのユーザの特定の認可」のステップに従ってください。

  • アプリケーションがOAuth Appなら、GitHubが顧客をInstallation URLにリダイレクトしたらすぐに認可フローを開始してください。 「OAuth Appの認可」のステップに従ってください。

どちらの種類のアプリケーションでも、最初のステップは顧客をhttps://github.com/login/oauth/authorizeにリダイレクトさせることです。

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

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

ステップ 4. 顧客アカウントのプロビジョニング

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

Note: In the current version of GitHub Marketplace, it's possible for a customer to purchase your app through GitHub Marketplace when they already have an existing account purchased from your app's website. If you find that you already have an account set up for the customer who purchased your app, please report the “double” purchases to GitHub Support.

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

Organizationのメンバーがアプリケーションへのアクセスを受け取る方法は、カスタマイズできます。 いくつかの例を挙げましょう。

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

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

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.