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ợ ưu đãi 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 ưu đãi bên ngoài, bao gồm cả điều kiện tham gia và phạm vi địa lý, hãy xem 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 ưu đãi bên ngoài, hãy thêm phiên bản 6.2.1 trở lên của phần phụ thuộc Thư viện Play Billing vào ứng dụng Android. 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 các ưu đãi 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 quy trình thanh toán mô tả, chỉ có một vài điểm sửa đổi khi khởi động BillingClient:

• Bạn cần gọi một phương thức mới để cho biết rằng bạn muốn sử dụng ưu đãi bên ngoài: enableExternalOffer.

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

Kotlin

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

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .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 xem có sẵn phim hay không

Ứng dụng của bạn nên xác nhận rằng có ưu đãi bên ngoài bằng cách gọi isExternalOfferAvailableAsync.

API này trả về BillingResponseCode.OK nếu có ưu đãi bên ngoài. Xem phần xử lý phản hồi để biết thông tin chi tiết 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.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.
      }

});

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

Để báo cáo giao dịch bên ngoài cho Google Play, bạn phải tạo mã thông báo giao dịch bên ngoài từ Thư viện Play Billing. Phải tạo mã giao dịch bên ngoài mới mỗi khi người dùng truy cập vào một trang web bên ngoài thông qua API mặt hàng bên ngoài. Bạn có thể thực hiện việc này bằng cách gọi API createExternalOfferReportingDetailsAsync. Mã thông báo này phải được tạo ngay trước khi người dùng được chuyển hướng ra ngoài ứng dụng. Mã này không bao giờ được lưu vào bộ nhớ đệm và phải tạo một mã mới mỗi khi người dùng được chuyển hướng ra bên ngoài ứng dụng.

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.
      }
});

Hộp thoại thông tin dành cho người dùng

Để tích hợp với các ưu đãi bên ngoài, ứng dụng đủ điều kiện của bạn phải cho thấy một màn hình thông tin giúp người dùng hiểu rằng họ sắp được chuyển hướng từ bên ngoài ứng dụng đến một trang web bên ngoài. Mỗi lần như vậy, bạn phải cho người dùng thấy màn hình thông tin bằng cách gọi API showExternalOfferInformationDialog trước khi liên kết đến một mặt hàng bên ngoài.

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);

Nếu phương thức này trả về BillingResponseCode.OK, thì ứng dụng của bạn có thể tiếp tục chuyển người dùng đến trang web bên ngoài. Nếu phương thức này trả về BillingResponseCode.USER_CANCELED, thì ứng dụng của bạn không được tiếp tục mở trang web.

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

Lưu ý: Hãy xem bài viết Đăng ký tham gia chương trình ưu đãi bên ngoài để biết các yêu cầu về báo cáo giao dịch.

Mọi giao dịch bên ngoài phải được báo cáo cho Google Play bằng cách gọi API Nhà phát triển Google Play từ phần phụ trợ. Các giao dịch bên ngoài phải được báo cáo khi cung cấp externalTransactionToken nhận được bằng API createExternalOfferReportingDetailsAsync. 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 một 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 isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync và showExternalOfferInformationDialog có thể trả về các phản hồi khác vớ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 thực hiện giao dịch hoặc mở trang web bên ngoài. Hãy thử lại bằng cách gọi showExternalOfferInformationDialog() để 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 hướng người dùng ra ngoài ứng dụng.
• FEATURE_NOT_SUPPORTED: Cửa hàng Play không hỗ trợ API mặt hàng bên ngoài trên thiết bị hiện tại. Đừng thực hiện giao dịch hoặc mở trang web bên ngoài.
• USER_CANCELED: Không mở trang web bên ngoài. Gọi showExternalOfferInformationDialog() lại để 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 hướng người dùng ra ngoài ứng dụng.
• BILLING_UNAVAILABLE: Giao dịch không đủ điều kiện cho các ưu đãi bên ngoài nên sẽ không thực hiện tiếp được theo chương trình này. Nguyên nhân là do 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à do lỗi thứ hai, 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 thích 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 tính nă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 được lập hoá đơn cho các giao dịch do tài khoản người kiểm thử được cấp phép thực hiện. Xem bài viết Kiểm thử 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ợ.