Hướng dẫn tích hợp chỉ áp dụng cho hệ thống thanh toán thay thế trong ứng dụng

Hướng dẫn này mô tả cách tích hợp các API để chỉ cung cấp hệ thống thanh toán thay thế (tức là không do người dùng chọn) trong các ứng dụng đủ điều kiện. Để tìm hiểu thêm về các chương trình này, bao gồm cả điều kiện tham gia và phạm vi địa lý áp dụng, hãy xem bài viết Giới thiệu về hệ thống thanh toán thay thế.

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

Thêm phần phụ thuộc Thư viện Play Billing vào ứng dụng Android của bạn. Để sử dụng các API hệ thống thanh toán thay thế, bạn cần sử dụng phiên bản 6.1 trở lên.

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 Google Play Billing mô tả, chỉ có một vài điểm sửa đổi khi khởi động BillingClient:

  • Để cho biết rằng ứng dụng của bạn chỉ sử dụng hệ thống thanh toán thay thế, bạn cần gọi một phương thức mới là: enableAlternativeBillingOnly.

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)
    .enableAlternativeBillingOnly()
    .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .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 điều kiện áp dụng

Ứng dụng của bạn nên xác nhận về việc chỉ có hệ thống thanh toán thay thế bằng cách gọi isAlternativeBillingOnlyAvailableAsync.

Nếu chỉ có hệ thống thanh toán thay thế thì API này sẽ trả về BillingResponseCode.OK. Hãy tham khảo 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.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Java


billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

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

Để chỉ tích hợp với hệ thống thanh toán thay thế, ứ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 Google Play sẽ không quản lý hoạt động thanh toán. 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 showAlternativeBillingOnlyInformationDialog trước khi bắt đầu quy trình thanh toán thay thế. Nếu người dùng đã xác nhận hộp thoại, thì thường là việc sử dụng API này sẽ không làm hộp thoại xuất hiện lại. Đôi khi hộp thoại sẽ xuất hiện lại với người dùng trong một số trường hợp, chẳng hạn như khi người dùng xoá bộ nhớ đệm trên thiết bị của họ.

Kotlin


// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

Java


// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(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 giao dịch. Trong trường hợp trả về BillingResponseCode.USER_CANCELED, ứng dụng của bạn nên gọi showAlternativeBillingOnlyInformationDialog để hiện lại hộp thoại cho người dùng. Để biết các mã phản hồi khác, hãy xem phần xử lý phản hồi.

Báo cáo giao dịch với Google Play

Mọi giao dịch thực hiện qua hệ thống thanh toán thay thế phải được báo cáo với Google Play bằng cách gọi API Nhà phát triển Google Play qua phần phụ trợ trong vòng 24 giờ, cung cấp một externalTransactionToken mà bạn sẽ nhận được bằng cách sử dụng API theo mô tả bên dưới. Bạn nên tạo một externalTransactionToken mới cho từng giao dịch mua hàng một lần, từng gói thuê bao mới, cũng như cho mọi lượt nâng cấp/hạ cấp một gói thuê bao hiện có. Để tìm hiểu cách báo cáo giao dịch sau khi nhận externalTransactionToken, hãy xem hướng dẫn tích hợp phần phụ trợ.

Kotlin

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

Java


billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Xử lý phản hồi

Các phương thức isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() và createAlternativeBillingOnlyReportingDetailsAsync() ở trên có thể trả về các phản hồi non-BillingResponseCode.OK trong trường hợp gặp lỗi. Bạn nên xử lý lỗi theo cách sau đây:

  • ERROR: Đây là lỗi nội bộ. Đừng tiếp tục giao dịch. Hãy thử lại bằng cách gọi showAlternativeBillingOnlyInformationDialog() để hiển thị hộp thoại thông tin cho người dùng vào lần tiếp theo người dùng tìm cách mua hàng.
  • FEATURE_NOT_SUPPORTED: Cửa hàng Play không hỗ trợ các API Hệ thống thanh toán thay thế trên thiết bị hiện tại. Hãy tiếp tục xử lý giao dịch thông qua hệ thống thanh toán thay thế. Bạn không cần báo cáo giao dịch này, cũng như mọi lần gia hạn các gói thuê bao bị ảnh hưởng với Google.
  • USER_CANCELED: Không tiếp tục giao dịch. Gọi showAlternativeBillingOnlyInformationDialog() lại để hiện hộp thoại thông tin cho người dùng vào lần tiếp theo người dùng cố gắng mua hàng.
  • BILLING_UNAVAILABLE: Giao dịch không đủ điều kiện để chỉ áp dụng hệ thống thanh toán thay thế 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 thử lại. Trong trường hợp SERVICE_DISCONNECTED thiết lập lại kết nối với Google Play trước khi thử lại.

Thử nghiệm hệ thống thanh toán thay thế

Bạn nên sử dụng tính năng nhân viên kiểm thử được cấp phép để kiểm thử quá trình tích hợp hệ thống thanh toán thay thế. 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ợ.