处理新购买和免费试用

当客户购买 GitHub Marketplace 应用的付费计划、免费试用版或免费版本时，你将收到带有 purchased 操作的 marketplace_purchase 事件 Webhook，此操作将启动购买流。

本文内容

Note

本文适用于仅在 GitHub Marketplace 中发布应用的情况。 若要详细了解如何在 GitHub Marketplace 中发布 GitHub Actions，请参阅“在 GitHub Marketplace 中发布操作”。

Warning

如果在 GitHub Marketplace 中提供 GitHub App，您的应用程序必须按照 OAuth 授权流程来识别用户。 您不需要设置单独的 OAuth app 来支持此流程。 有关详细信息，请参阅“代表用户使用 GitHub 应用进行身份验证”。

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

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

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

然后，GitHub Enterprise Cloud 将带有 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 Enterprise Cloud 在客户购买时会提示他们选择应用程序可以访问哪些仓库。 然后，GitHub Enterprise Cloud 将应用程序安装在客户选择的帐户上，并授予对所选仓库的访问权限。

此时，如果你在 GitHub App 设置中指定了“设置 URL”，则 GitHub Enterprise Cloud 将客户重定向到该 URL。 如果您没有指定设置 URL，则无法处理购买 GitHub App 的购买。

Note

“设置 URL”在 GitHub App 设置中被描述为可选字段，但如果你要在 GitHub Marketplace 中提供应用，则它为必填字段****。 有关详细信息，请参阅“关于设置 URL”。

如果您的应用程序是 OAuth app，GitHub Enterprise Cloud 不会在任何地方安装它。 相反，GitHub Enterprise Cloud 会将客户重定向到你在 GitHub Marketplace 上架信息中指定的安装 URL。

当客户购买 OAuth app 时，GitHub Enterprise Cloud 会将客户重定向到你选择的 URL（设置 URL 或安装 URL），并且该 URL 会以查询参数的形式加入客户选择的定价计划：marketplace_listing_plan_id。

步骤 3. 授权

当客户购买您的应用程序时，您必须通过 OAuth 授权流程发送客户：

  • 如果应用是 GitHub App，只要 GitHub Enterprise Cloud 将客户重定向到设置 URL 便开始授权流。 按照“代表用户使用 GitHub 应用进行身份验证”中的步骤操作。

  • 如果应用是 OAuth app，只要 GitHub Enterprise Cloud 将客户重定向到安装 URL 便开始授权流。 按照“授权 OAuth 应用”中的步骤操作。

对于任一类型的应用，第一步都是将客户重定向到 https://github.com/login/oauth/authorize。

客户完成授权后，您的应用程序将收到客户的 OAuth 访问令牌。 下一步将需要使用此令牌。

Note

授权客户免费试用时，请授予他们与付费计划相同的访问权限。 试用期结束后，将其移至付费计划。

步骤 4. 预配客户帐户

您的应用程序必须为所有新购买预配客户帐户。 使用在“步骤 3.授权”中你为客户收到的访问令牌，调用 GET /user/marketplace_purchases 终结点。 响应将包括客户的 account 信息，并显示他们是否在使用免费试用版 (on_free_trial)。 使用此信息完成设置和预配。

Note

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

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

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

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

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