Di chuyển từ Thư viện Google Play Billing phiên bản 7 hoặc 8 sang phiên bản 9

Tài liệu này mô tả cách di chuyển từ Google Play Billing Library (PBL) 7 hoặc 8 sang PBL 9 và cách tích hợp với các tính năng mới.

Để biết danh sách đầy đủ các thay đổi trong phiên bản 9.0.0, hãy tham khảo ghi chú phát hành.

Tổng quan

PBL 9 có những điểm cải tiến đối với các API hiện có, đồng thời xoá các API đã ngừng sử dụng trước đó. Phiên bản thư viện này cũng giới thiệu ngữ cảnh lỗi phong phú hơn thông qua các mã phản hồi phụ mới.

Khả năng tương thích ngược cho bản nâng cấp PBL

Để di chuyển sang PBL 9, bạn cần cập nhật hoặc xoá một số tài liệu tham khảo API hiện có khỏi ứng dụng của mình, như mô tả trong ghi chú phát hành và sau đó trong hướng dẫn di chuyển này.

Nâng cấp từ PBL 7 hoặc 8 lên PBL 9

Để nâng cấp từ PBL 7 hoặc 8 lên PBL 9, hãy làm theo các bước sau:

  1. Cập nhật phiên bản phần phụ thuộc Thư viện Play Billing trong tệp build.gradle của ứng dụng.

    dependencies {
  def billing_version = "9.0.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Nếu bạn đang sử dụng Kotlin, mô-đun KTX của Thư viện Google Play Billing chứa các tiện ích và coroutine của Kotlin, cho phép bạn viết mã Kotlin tương thích khi sử dụng Thư viện Google Play Billing. Để đưa các phần mở rộng này vào dự án, hãy thêm phần phụ thuộc sau vào tệp build.gradle của ứng dụng như sau:

    dependencies {
  val billing_version = "9.0.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Chỉ áp dụng cho bản nâng cấp từ PBL 7 lên PBL 9). Cập nhật việc triển khai phương thức queryProductDetailsAsync.

    Có một thay đổi trong chữ ký của phương thức ProductDetailsResponseListener.onProductDetailsResponse. Điều này đòi hỏi bạn phải thay đổi trong ứng dụng để triển khai queryProductDetailsAsync. Để biết thêm thông tin, hãy xem bài viết Hiển thị các sản phẩm có sẵn để mua.

  3. Xử lý các API đã bị xoá.

    Bảng sau đây liệt kê các API bị xoá và các API thay thế tương ứng mà bạn phải dùng trong ứng dụng của mình.

    Nâng cấp từ

    PBL 9 không còn hỗ trợ các API được liệt kê trong bảng sau. Nếu quá trình triển khai của bạn sử dụng bất kỳ API nào trong số này, hãy tham khảo bảng để biết các API thay thế tương ứng.

    Xoá API không dùng nữa trước đây API thay thế để sử dụng
    queryPurchaseHistoryAsync API Xem phần Truy vấn nhật ký mua hàng. Nếu đang dùng queryPurchaseHistoryAsync để xác định điều kiện dùng thử miễn phí, thì giờ đây, bạn nên dùng ProductDetails.getSubscriptionOfferDetails() để xác định những ưu đãi mà người dùng đủ điều kiện sử dụng.
    BillingClient.SkuType BillingClient.ProductType. Các hằng số loại sản phẩm INAPP và SUBS vẫn có chức năng tương tự như các hằng số loại SKU không dùng nữa.
    SkuDetails ProductDetails. Đây là mô hình dữ liệu mới hỗ trợ các sản phẩm tính phí một lần.
    SkuDetailsParams Sử dụng QueryProductDetailsParams với queryProductDetailsAsync.
    SkuDetailsResponseListener Sử dụng ProductDetailsResponseListener với queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Sử dụng queryPurchasesAsync cho các giao dịch mua đang hoạt động hoặc đang chờ xử lý.
    • Theo dõi các giao dịch mua đã sử dụng trên máy chủ phụ trợ.
    • Sử dụng Voided Purchases API phía máy chủ cho các giao dịch mua bị huỷ hoặc vô hiệu.
    getSkuDetailsList và setSkuDetailsList Sử dụng BillingFlowParams.Builder.setProductDetailsParamsList
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API không có tham số) enablePendingPurchases(PendingPurchasesParams params)
    Xin lưu ý rằng enablePendingPurchases() không dùng nữa có chức năng tương đương với enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Nâng cấp từ

    Bảng sau đây liệt kê các API bị xoá trong PBL 9 và các API thay thế tương ứng mà bạn phải dùng trong ứng dụng.

    Xoá API không dùng nữa trước đây API thay thế để sử dụng
    BillingClient.SkuType BillingClient.ProductType. Các hằng số loại sản phẩm INAPP và SUBS vẫn có chức năng tương tự như các hằng số loại SKU không dùng nữa.
    SkuDetails ProductDetails. Đây là mô hình dữ liệu mới hỗ trợ các sản phẩm tính phí một lần.
    SkuDetailsParams Sử dụng QueryProductDetailsParams với queryProductDetailsAsync.
    SkuDetailsResponseListener Sử dụng ProductDetailsResponseListener với queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Sử dụng queryProductDetailsAsync cho các giao dịch mua đang hoạt động hoặc đang chờ xử lý.
    • Theo dõi các giao dịch mua đã sử dụng trên máy chủ phụ trợ.
    • Sử dụng Voided Purchases API phía máy chủ cho các giao dịch mua bị huỷ hoặc vô hiệu.
    getSkuDetailsList và setSkuDetailsList Sử dụng BillingFlowParams.Builder.setProductDetailsParamsList

  4. (Nên dùng) Bật tính năng tự động kết nối lại dịch vụ.

    Thư viện Play Billing có thể tự động tìm cách thiết lập lại kết nối dịch vụ nếu một lệnh gọi API được thực hiện trong khi dịch vụ bị ngắt kết nối. Để biết thêm thông tin, hãy xem bài viết Bật tính năng tự động kết nối lại dịch vụ.

  5. Xử lý mã phản hồi phụ mới.

    BillingResult do launchBillingFlow() trả về hiện sẽ bao gồm một trường mã phản hồi phụ. Trường này sẽ chỉ được điền sẵn trong một số trường hợp để cung cấp lý do cụ thể hơn cho lỗi. Trường phản hồi phụ có thể có các giá trị sau:

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS – Trả về khi số tiền của người dùng ít hơn giá của mặt hàng mà họ đang cố gắng mua.
    • USER_INELIGIBLE – Trả về khi người dùng không đáp ứng các yêu cầu về điều kiện được định cấu hình cho một ưu đãi thuê bao.
    • NO_APPLICABLE_SUB_RESPONSE_CODE – Giá trị mặc định, được trả về khi không có mã phản hồi phụ nào khác có thể áp dụng.

    Bước di chuyển: Cập nhật PurchasesUpdatedListener hoặc phương thức xử lý kết quả tương đương để nhận dạng và phản hồi các mã phản hồi phụ cụ thể này nhằm mang lại trải nghiệm người dùng tốt hơn. Ví dụ: nhắc người dùng sửa phương thức thanh toán hoặc cho thấy một thông báo lỗi cụ thể.

  6. Nhận biết việc phân loại lại mã lỗi.

    Trong trường hợp ứng dụng Cửa hàng Play bị hệ thống chặn (ví dụ: trong chế độ tuỳ chỉnh dành cho trẻ em của OEM), mã phản hồi từ PBL đã thay đổi từ ERROR thành BILLING_UNAVAILABLE.

    Bước di chuyển: Đảm bảo logic xử lý lỗi của bạn đáp ứng thay đổi này và không dựa vào việc nhận được lỗi chung trong những trường hợp cụ thể này.

  7. Xử lý tính chất rỗng DeveloperProvidedBillingDetails.getLinkUri().

    Nếu bạn sử dụng DeveloperProvidedBillingDetails trong quá trình tích hợp phương thức thanh toán bên ngoài, thì getLinkUri() hiện là @Nullable.

    Bước di chuyển: Để xử lý thay đổi này một cách an toàn, hãy đảm bảo mã tích hợp của bạn xử lý cả giá trị null và giá trị chuỗi trống ("") từ phương thức DeveloperProvidedBillingDetails.getLinkUri() trước khi phân tích cú pháp hoặc chạy các ý định của trình duyệt. Ví dụ:

    Kotlin

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. Thay đổi không bắt buộc.