我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

Handling new purchases and free trials

When a customer purchases a paid plan, free trial, or the free version of your GitHub Marketplace app, you'll receive the marketplace_purchase event webhook with the purchased action, which kicks off the purchasing flow.

本文内容

If you offer a GitHub App in GitHub Marketplace, your app must identify users following the OAuth authorization flow. You don't need to set up a separate OAuth App to support this flow. 更多信息请参阅“识别和授权 GitHub 应用程序用户”。

步骤 1. Initial purchase and webhook event

Before a customer purchases your GitHub Marketplace app, they select a listing plan. They also choose whether to purchase the app from their personal account or an organization account.

The customer completes the purchase by clicking Complete order and begin installation.

GitHub then sends the marketplace_purchase webhook with the purchased action to your app.

Read the effective_date and marketplace_purchase object from the marketplace_purchase webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins.

If your app offers a free trial, read the marketplace_purchase[on_free_trial] attribute from the webhook. If the value is true, your app will need to track the free trial start date (effective_date) and the date the free trial ends (free_trial_ends_on). Use the free_trial_ends_on date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your billing UI. To learn how to handle cancellations before a free trial ends, see "Cancelling plans." See "Upgrading and downgrading plans" to find out how to transition a free trial to a paid plan when a free trial expires.

See "GitHub Marketplace webhook events" for an example of the marketplace_purchase event payload.

步骤 2. 安装

If your app is a GitHub App, GitHub prompts the customer to select which repositories the app can access when they purchase it. GitHub then installs the app on the account the customer selected and grants access to the selected repositories.

At this point, if you specified a Setup URL in your GitHub App settings, Github will redirect the customer to that URL. If you do not specify a setup URL, you will not be able to handle purchases of your GitHub App.

Note: The Setup URL is described as optional in GitHub App settings, but it is a required field if you want to offer your app in GitHub Marketplace.

If your app is an OAuth App, GitHub does not install it anywhere. Instead, GitHub redirects the customer to the Installation URL you specified in your GitHub Marketplace listing.

When a customer purchases an OAuth App, GitHub redirects the customer to the URL you choose (either Setup URL or Installation URL) and the URL includes the customer's selected pricing plan as a query parameter: marketplace_listing_plan_id.

步骤 3. 授权

When a customer purchases your app, you must send the customer through the OAuth authorization flow:

  • If your app is a GitHub App, begin the authorization flow as soon as GitHub redirects the customer to the Setup URL. Follow the steps in "Identifying and authorizing users for GitHub Apps."

  • If your app is an OAuth App, begin the authorization flow as soon as GitHub redirects the customer to the Installation URL. Follow the steps in "Authorizing OAuth Apps."

For either type of app, the first step is to redirect the customer to https://github.com/login/oauth/authorize.

After the customer completes the authorization, your app receives an OAuth access token for the customer. You'll need this token for the next step.

Note: When authorizing a customer on a free trial, grant them the same access they would have on the paid plan. You'll move them to the paid plan after the trial period ends.

步骤 4. Provisioning customer accounts

Your app must provision a customer account for all new purchases. Using the access token you received for the customer in Step 3. Authorization, call the "List subscriptions for the authenticated user" endpoint. The response will include the customer's account information and show whether they are on a free trial (on_free_trial). Use this information to complete setup and provisioning.

注:在当前版本的 GitHub Marketplace 中,如果客户已有一个从您的应用程序网站购买的现有帐户,他们可能还会通过 GitHub Marketplace 购买您的应用程序。 如果您发现已经为购买您的应用程序的客户设置了帐户,请向 GitHub 支持部门报告这种“双重”购买的情况。

If the purchase is for an organization and per-user, you can prompt the customer to choose which organization members will have access to the purchased app.

You can customize the way that organization members receive access to your app. Here are a few suggestions:

Flat-rate pricing: If the purchase is made for an organization using flat-rate pricing, your app can get all the organization’s members via the API and prompt the organization admin to choose which members will have paid users on the integrator side.

Per-unit pricing: One method of provisioning per-unit seats is to allow users to occupy a seat as they log in to the app. Once the customer hits the seat count threshold, your app can alert the user that they need to upgrade through GitHub Marketplace.

此文档对您有帮助吗?

Privacy policy

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。