处理新购买和免费试用

步骤 1. 首次购买和 web 挂钩事件

客户在购买 GitHub Marketplace 应用之前，需要选择上架产品计划。 他们还要选择是从个人帐户还是从组织帐户购买应用程序。

客户通过单击“完成订单并开始安装”来完成购买。

然后，GitHub 将带有 purchased 操作的 marketplace_purchase Webhook 发送到你的应用。

从 marketplace_purchase Webhook 读取 effective_date 和 marketplace_purchase 对象，以确定客户购买了哪个计划、何时开始计费周期以及何时开始下一个计费周期。

如果应用提供免费试用版，则从 Webhook 读取 marketplace_purchase[on_free_trial] 属性。 如果该值为 true，则应用需要跟踪免费试用开始日期 (effective_date) 和免费试用结束日期 (free_trial_ends_on)。 使用 free_trial_ends_on 日期在应用的 UI 中显示免费试用剩余天数。 可以在横幅或计费 UI中显示。 若要了解如何在免费试用结束前处理取消，请参阅“处理计划取消”。 请参阅“处理计划更改”，了解在免费试用期满后如何从免费试用版过渡到付费计划。

有关 marketplace_purchase 事件有效负载的示例，请参阅“GitHub Marketplace API 的 web 挂钩事件”。

步骤 2. 安装

如果您的应用程序是 GitHub App， GitHub 在客户购买时会提示他们选择应用程序可以访问哪些仓库。 然后，GitHub 将应用程序安装在客户选择的帐户上，并授予对所选仓库的访问权限。

此时，如果你在 GitHub App 设置中指定了“设置 URL”，则 GitHub 将客户重定向到该 URL。 如果您没有指定设置 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)。 使用此信息完成设置和预配。

如果客户是为组织按用户购买应用程序，您可以提示客户选择哪些组织成员将有权访问所购买的应用程序。

您可以自定义组织成员获取应用程序访问权限的方式。 以下是一些建议：

统一定价****：如果组织使用统一定价购买应用，你的应用可通过 API 获取组织的所有成员，并提示组织所有者选择哪些成员可以在集成者一方包含付费用户。

按单位定价：一种按单位预配席位的方法，允许用户在登录应用时占用一个席位。 一旦客户达到席位数阈值，您的应用程序就可以提醒用户他们需要通过 GitHub Marketplace 进行升级。