外部内容链接的应用内集成指南

本文档介绍了如何集成 Play 结算库 API，以便在符合条件的应用中提供外部内容链接。这包括能够将美国境内的用户引导至 Play 应用之外，以便向用户提供应用内数字内容和应用下载的优惠。如需详细了解此计划，请参阅计划要求。

Play 结算库设置

向您的 Android 应用添加 Play 结算库依赖项。如需使用外部链接 API，您需要使用 8.2 或更高版本。如果您需要从较早版本迁移，请先按照迁移指南中的说明操作，然后再添加外部内容链接。

初始化结算客户端

如需初始化结算客户端，请按照初始化 BillingClient 中所述的步骤操作，但需进行以下修改：

  • 请勿启用 PurchasesUpdatedListener - 外部内容链接不需要此监听器。
  • 使用 enableBillingProgram() 调用 BillingProgram.EXTERNAL_CONTENT_LINK 来指明您的应用使用外部内容链接。

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

连接到 Google Play

初始化 BillingClient 后，请按照连接到 Google Play 中的说明连接到 Google Play。

检查用户资格

连接到 Google Play 后，您必须通过调用 isBillingProgramAvailableAsync() 方法来检查用户是否符合外部内容链接计划的条件。如果用户符合外部内容链接计划的条件，此方法会返回 BillingResponseCode.OK。以下示例展示了如何检查用户是否符合外部内容链接的条件：

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

如需详细了解您的应用应如何响应其他响应代码，请参阅响应处理部分。如果您使用 Kotlin 扩展，则可以使用 Kotlin 协程，因此无需定义单独的监听器。

准备外部交易令牌

接下来，您必须从 Play Billing 库生成外部交易令牌。每次用户通过外部链接 API 访问外部网站时，都必须生成新的外部交易令牌。您可以通过调用 createBillingProgramReportingDetailsAsync API 来完成此操作。令牌应在用户链接出去之前立即生成。

注意：外部交易令牌绝不应缓存，并且每次用户链接出去时都应生成新令牌。

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

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

如果您使用 Kotlin 扩展，则可以使用 Kotlin 协程，因此无需定义单独的监听器。

启动外部链接

外部交易令牌准备就绪后，用户可以通过调用 launchExternalLink 方法在应用外部链接到数字内容优惠或应用下载。当您调用此 API 时，Google Play 可能会根据用户的用户设置向用户呈现其他信息对话框。

调用 launchExternalLink 方法时，必须通过 LaunchExternalLinkParams 提供外部链接的详细信息。此类包含以下参数：

  • 链接 URI - 提供数字内容或应用下载的外部网站的链接。对于应用下载，此链接必须在 Play 管理中心内注册并获得批准。
  • 链接类型 - 向用户提供的内容类型。
  • 启动模式 - 指定链接的启动方式。对于应用下载，您必须将此属性设置为 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP。

  • 结算计划 - 将此项设置为 BillingProgram.EXTERNAL_CONTENT_LINK。

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

响应处理

发生错误时，方法 isBillingProgramAvailableAsync()、createBillingProgramReportingDetailsAsync() 和 onLaunchExternalLinkResponse() 可能会提供除 BillingResponseCode.OK 之外的 BillingResponseCode。请考虑按如下方式处理这些响应代码：

  • ERROR：这是内部错误。请勿继续进行交易或打开外部网站。通过再次调用 API 或在下次尝试将用户引导至应用外部时调用 launchExternalLink() 来重试。
  • FEATURE_NOT_SUPPORTED：当前设备上的 Play 商店不支持外部内容链接 API。请勿继续进行交易或打开外部网站。
  • USER_CANCELED：不继续打开外部网站。下次尝试将用户引导至应用外部时，请再次调用 launchExternalLink()。
  • BILLING_UNAVAILABLE：交易无法使用外部内容链接，因此不应按照此计划继续进行。这是因为用户不在符合此计划条件的国家/地区，或者您的账号未成功注册此计划。如果是后一种情况，请在 Play 管理中心内检查您的注册状态。
  • DEVELOPER_ERROR：请求中存在错误。使用调试消息找出并更正错误，然后再继续交易。
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：这些是暂时性错误，应通过适当的重试政策进行处理。如果发生 SERVICE_DISCONNECTED 错误，请重新与 Google Play 建立连接，然后再重试。

测试外部内容链接

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

后续步骤

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