针对外部优惠计划的应用内集成指南

本指南介绍了如何集成 API 以支持外部优惠 在符合条件的应用和地区推出。详细了解外部优惠计划 包括资格要求和地理范围，请参阅 计划要求。

Play 结算库设置

如需使用外部优惠 API，请执行以下操作： 添加 6.2.1 版或更高版本的 Play 结算库依赖项 您的 Android 应用如果您需要从早期版本迁移，请按照 请参阅迁移指南中的说明，然后再尝试实施 外部优惠。

连接到 Google Play

集成流程的最初步骤与 结算集成指南中有一些建议， 初始化 BillingClient：

  • 您需要调用一个新方法，指明要在外部使用外部 提供：enableExternalOffer。

以下示例演示了如何通过这些调整来初始化 BillingClient：

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

初始化 BillingClient 后，您需要按照集成指南中的说明与 Google Play 建立连接。

查看空房情况

您的应用应通过调用 isExternalOfferAvailableAsync。

如果有外部优惠，此 API 会返回 BillingResponseCode.OK。 如需详细了解您的应用应如何处理，请参阅响应处理 对其他响应代码进行响应。

Kotlin


billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
})

Java


billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }

});

准备外部交易令牌

要向 Google Play 报告外部交易，您必须拥有一个外部 Play 结算库生成的交易令牌。新的外部 每次用户访问外部 通过外部优惠 API 访问网站。这可以通过调用 createExternalOfferReportingDetailsAsync API。此令牌应为 系统会在用户被定向到应用外部紧接着生成它应该 永不缓存，并且每次引导用户时都应生成一个新的密钥 。

Kotlin


billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java


billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

面向用户的信息对话框

如需与外部优惠集成，符合条件的应用必须显示相关信息 这个界面可以帮助用户了解 将应用关联到外部网站信息屏幕必须通过 先调用 showExternalOfferInformationDialog API，然后再链接到 每次外部优惠

Kotlin


// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java


// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

如果此方法返回 BillingResponseCode.OK，您的应用可以继续 将用户定向到外部网站。如果该方法返回 BillingResponseCode.USER_CANCELED，您的应用不得继续打开 网站。

向 Google Play 报告交易

所有外部交易都必须报告给 Google Play 从后端调用 Google Play Developer API。外部交易 同时提供 externalTransactionToken 通过 createExternalOfferReportingDetailsAsync API。如果用户多次提交 购买时，您可以使用 externalTransactionToken来报告每笔购买交易。要了解如何举报 请参阅后端集成指南。

响应处理

发生错误时，isExternalOfferAvailableAsync 方法、 createExternalOfferReportingDetailsAsync和 showExternalOfferInformationDialog 可能会返回 BillingResponseCode.OK。请考虑按如下方式处理这些响应代码：

  • ERROR：这是内部错误。不继续进行交易，或 打开外部网站。拨打电话重试 showExternalOfferInformationDialog()，用于显示信息 对话框，则会再次显示正确的对话框。 应用。
  • FEATURE_NOT_SUPPORTED：此 API 不支持外部优惠 API 当前设备上的 Play 商店不继续进行交易，或 打开外部网站。
  • USER_CANCELED：不继续打开外部网站。致电 showExternalOfferInformationDialog() 以显示信息 对话框，则会再次显示 应用。
  • BILLING_UNAVAILABLE：交易不符合使用外部优惠的条件 因此不应在该程序下继续。这是因为 用户不在符合此计划条件的国家/地区，或者您的账号存在 未能成功加入该计划。如果是后一种情况，请查看 。
  • DEVELOPER_ERROR：请求中存在错误。使用调试消息找出并更正错误，然后再继续交易。
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：分别是 应通过适当的重试政策进行处理的暂时性错误。 如果是 SERVICE_DISCONNECTED，请通过以下应用重新建立连接： 然后重试。

测试外部优惠

许可测试人员应该用于测试外部优惠集成。您 对于许可测试人员发起的交易，系统不会开具账单 账号。如需了解详情，请参阅使用应用许可测试应用内购结算功能 了解如何配置许可测试人员

后续步骤

完成应用内集成后，您就可以集成后端了。