Hướng dẫn tích hợp trong ứng dụng cho chương trình ưu đãi bên ngoài

Hướng dẫn này mô tả cách tích hợp với các API để hỗ trợ việc chào bán bên ngoài trong các ứng dụng và khu vực đủ điều kiện. Để tìm hiểu thêm về chương trình chào bán bên ngoài, bao gồm cả điều kiện tham gia và phạm vi địa lý áp dụng, hãy xem các yêu cầu của chương trình.

Thiết lập Thư viện Play Billing

Để sử dụng các API chào bán bên ngoài, hãy thêm phần phụ thuộc Thư viện Play Billing phiên bản 8.2 trở lên vào ứng dụng Android của bạn. Nếu bạn cần di chuyển từ phiên bản cũ sang, hãy làm theo hướng dẫn trong hướng dẫn di chuyển trước khi triển khai tính năng chào bán bên ngoài.

Kết nối với Google Play

Các bước đầu tiên trong quy trình tích hợp cũng giống như các bước tương ứng mà hướng dẫn tích hợp dịch vụ thanh toán mô tả, ngoại trừ việc bạn phải gọi enableBillingProgram để cho biết rằng bạn muốn sử dụng ưu đãi bên ngoài khi khởi động BillingClient:

Ví dụ sau minh hoạ việc khởi động BillingClient với một số điểm sửa đổi:

Kotlin

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

Java

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

Sau khi khởi động BillingClient, bạn cần thiết lập kết nối với Google Play theo mô tả trong hướng dẫn tích hợp.

Kiểm tra phạm vi cung cấp

Để xác nhận rằng người dùng hiện tại có thể sử dụng các sản phẩm bên ngoài, hãy gọi isBillingProgramAvailableAsync.

API này trả về BillingResponseCode.OK nếu có ưu đãi bên ngoài. Hãy xem phần xử lý phản hồi để biết thông tin cụ thể về cách ứng dụng của bạn sẽ phản hồi các mã phản hồi khác.

Kotlin


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingResult: BillingResult,
      billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails) {
        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.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        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.
      }
  });

Chuẩn bị mã thông báo giao dịch bên ngoài

Để báo cáo một giao dịch bên ngoài cho Google Play, bạn phải có mã giao dịch bên ngoài được tạo từ Thư viện Google Play Billing. Bạn có thể lấy mã thông báo này bằng cách gọi API createBillingProgramReportingDetailsAsync. Bạn phải tạo một mã thông báo mới ngay trước khi đưa người dùng ra bên ngoài ứng dụng cho từng ưu đãi bên ngoài. Không được lưu mã thông báo vào bộ nhớ đệm trong các giao dịch.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Ngoài ra, bạn có thể truy vấn hàm tạm ngưng createBillingProgramReportingDetailsAsync bằng tiện ích Kotlin để không cần xác định một trình nghe:

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

Bắt đầu quy trình chào bán bên ngoài

Để bắt đầu quy trình chào bán bên ngoài, ứng dụng đủ điều kiện của bạn phải gọi API launchExternalLink() từ luồng chính của ứng dụng. API này nhận dữ liệu đầu vào là một đối tượng LaunchExternalLinkParams. Để tạo một đối tượng LaunchExternalLinkParams, hãy dùng lớp LaunchExternalLinkParams.Builder. Lớp này chứa các tham số sau:

  • linkUri – Đường liên kết đến trang web bên ngoài nơi cung cấp nội dung kỹ thuật số hoặc ứng dụng có thể tải xuống. Đối với lượt tải ứng dụng xuống, bạn phải đăng ký và được phê duyệt đường liên kết này trong Play Console.
  • linkType – Loại nội dung được cung cấp cho người dùng.
  • launchMode – Chỉ định cách khởi chạy đường liên kết. Đối với lượt tải ứng dụng xuống, bạn phải đặt giá trị này thành LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram – Đặt giá trị này thành BillingProgram.EXTERNAL_OFFER.

Khi bạn gọi launchExternalLink(), hệ thống có thể hiển thị các hộp thoại thông tin bổ sung cho người dùng dựa trên chế độ cài đặt người dùng của họ. Tuỳ thuộc vào tham số launchMode, Play sẽ khởi chạy URI đường liên kết trong một trình duyệt bên ngoài hoặc trả về quy trình cho ứng dụng của bạn để khởi chạy URI. Trong hầu hết trường hợp, bạn có thể sử dụng chế độ LAUNCH_IN_EXTERNAL_BROWSER_OR_APP. Trong chế độ này, Play sẽ khởi chạy URI cho bạn. Nếu muốn có hành vi tuỳ chỉnh hơn, chẳng hạn như khởi chạy URI trong webview hoặc mở URI trong một trình duyệt cụ thể, bạn có thể sử dụng chế độ CALLER_WILL_LAUNCH_LINK. Để bảo vệ quyền riêng tư của người dùng, hãy đảm bảo rằng không có thông tin nhận dạng cá nhân (PII) nào được truyền trong URI.

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

Java


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

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .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.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Nếu đặt LaunchMode thành CALLER_WILL_LAUNCH_LINK, bạn chỉ nên chuyển hướng người dùng ra khỏi ứng dụng nếu onLaunchExternalLinkResponse cung cấp BillingResponseCode.OK.

Báo cáo giao dịch cho Google Play

Bạn phải báo cáo tất cả giao dịch bên ngoài cho Google Play bằng cách gọi API Nhà phát triển Google Play qua phần phụ trợ. Khi báo cáo một giao dịch, bạn phải cung cấp externalTransactionToken nhận được từ API createBillingProgramReportingDetailsAsync. Nếu người dùng thực hiện nhiều giao dịch mua, bạn có thể sử dụng cùng một externalTransactionToken để báo cáo từng giao dịch mua. Để tìm hiểu cách báo cáo giao dịch, hãy xem hướng dẫn tích hợp phần phụ trợ.

Xử lý phản hồi

Khi xảy ra lỗi, các phương thức isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() và launchExternalLink() có thể trả về các phản hồi khác ngoài BillingResponseCode.OK. Hãy cân nhắc xử lý các mã phản hồi này như sau:

  • ERROR: Đây là lỗi nội bộ. Đừng tiếp tục giao dịch hoặc mở trang web bên ngoài. Thử lại bằng cách gọi launchExternalLink() để hiển thị hộp thoại thông tin cho người dùng vào lần tiếp theo bạn cố gắng chuyển hướng người dùng ra ngoài ứng dụng.
  • FEATURE_NOT_SUPPORTED: Cửa hàng Play không hỗ trợ các API ưu đãi bên ngoài trên thiết bị hiện tại. Đừng tiếp tục giao dịch hoặc mở trang web bên ngoài.
  • USER_CANCELED: Không tiếp tục mở trang web bên ngoài. Gọi lại launchExternalLink() để hiển thị hộp thoại thông tin cho người dùng vào lần tiếp theo bạn cố gắng chuyển hướng người dùng ra khỏi ứng dụng.
  • BILLING_UNAVAILABLE: Giao dịch không đủ điều kiện để chào bán bên ngoài nên sẽ không thực hiện tiếp được theo chương trình này. Lý do là vì người dùng không ở quốc gia đủ điều kiện để tham gia chương trình này, hoặc tài khoản của bạn chưa đăng ký tham gia chương trình. Nếu là vì lý do thứ hai, thì hãy kiểm tra trạng thái đăng ký của bạn trong Play Console.
  • DEVELOPER_ERROR: Yêu cầu này gặp phải lỗi. Hãy sử dụng thông báo gỡ lỗi để xác định và sửa lỗi trước khi tiếp tục.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Đây là các lỗi tạm thời và bạn cần xử lý bằng một chính sách thử lại phù hợp. Trong trường hợp SERVICE_DISCONNECTED, hãy thiết lập lại kết nối với Google Play trước khi thử lại.

Thử nghiệm ưu đãi bên ngoài

Bạn nên sử dụng người kiểm thử được cấp phép để kiểm thử việc tích hợp ưu đãi bên ngoài. Bạn sẽ không nhận được hoá đơn cho những giao dịch do tài khoản người kiểm thử được cấp phép thực hiện. Hãy xem phần Kiểm nghiệm tính năng thanh toán trong ứng dụng bằng quy trình cấp phép ứng dụng để biết thêm thông tin về cách định cấu hình nhân viên kiểm thử được cấp phép.

Các bước tiếp theo

Sau khi hoàn tất quy trình tích hợp trong ứng dụng, bạn đã sẵn sàng tích hợp phần phụ trợ.