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

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

Play 计费库设置

要使用外部优惠 API，请 将 Play 计费库依赖项的 6.2.1 或更高版本添加到您的 Android 应用。如果您需要从早期版本迁移，请在尝试实施外部优惠之前，按照 迁移指南 中的说明操作。

连接到 Google Play

集成过程的最初步骤与 计费集成指南 中描述的步骤相同，在 初始化 BillingClient 时有一些修改。

以下示例演示了使用这些修改初始化 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 开发者 API 来报告给 Google Play。报告外部交易时，必须提供使用 createExternalOfferReportingDetailsAsync API 获取的 externalTransactionToken。如果用户进行多次购买，您可以使用相同的 externalTransactionToken 报告每次购买。要了解如何报告交易，请参阅 后端集成指南。

响应处理

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

  • ERROR：这是内部错误。请勿继续进行交易或打开外部网站。通过再次调用 showExternalOfferInformationDialog() 显示信息对话框，以便在下一次尝试引导用户离开应用时向用户显示该对话框。
  • FEATURE_NOT_SUPPORTED：当前设备上的 Play 商店不支持外部优惠 API。请勿继续进行交易或打开外部网站。
  • USER_CANCELED：请勿继续打开外部网站。再次调用 showExternalOfferInformationDialog() 显示信息对话框，以便在下一次尝试引导用户离开应用时向用户显示该对话框。
  • BILLING_UNAVAILABLE：交易不符合外部优惠条件，因此不应在此计划下进行。这可能是因为用户不在此计划的合格国家/地区，或者您的帐户尚未成功加入此计划。如果是后者，请在 Play 开发者控制台中检查您的注册状态。
  • DEVELOPER_ERROR：请求存在错误。在继续操作之前，请使用调试消息识别并更正错误。
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：这些是应该使用适当重试策略处理的瞬态错误。在 SERVICE_DISCONNECTED 的情况下，请先重新建立与 Google Play 的连接，然后再重试。

测试外部优惠

应使用许可证测试人员来测试您的外部优惠集成。对于由许可证测试人员帐户发起的交易，您将不会被开具发票。有关配置许可证测试人员的更多信息，请参阅 使用应用许可测试应用内结算。

后续步骤

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