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ừ Thư viện Google Play Billing (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ó các điểm cải tiến cho API hiện có, đồng thời xoá các API đã ngừng hoạt động trước đó. Phiên bản này của thư viện cũng cung cấp bối 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ệp tham chiếu API hiện có khỏi ứng dụng, như mô tả trong ghi chú phát hành và phần 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.1.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.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Chỉ áp dụng cho việc nâng cấp từ PBL 7 lên PBL 9). Cập nhật cách 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 hỏi bạn phải thay đổi ứng dụng để triển khai queryProductDetailsAsync. Để biết thêm thông tin, hãy xem phần Hiển thị tình trạng còn hàng của sản phẩm.

  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 sử 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ố các API đã bị xoá 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
    API queryPurchaseHistoryAsync Xem phần Truy vấn nhật ký mua hàng. Nếu đang sử dụng queryPurchaseHistoryAsync để xác định điều kiện dùng thử miễn phí, thì giờ đây, bạn nên sử dụng ProductDetails.getSubscriptionOfferDetails() để xác định những ưu đãi mà người dùng đủ điều kiện nhận.
    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 đã tiêu thụ 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 sử dụng trong ứng dụng của mình.

    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 đã tiêu thụ 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ìm cách tự động thiết lập lại kết nối dịch vụ nếu 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 phần 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 được trả về từ launchBillingFlow() hiện sẽ bao gồm một trường mã phản hồi phụ. Trường này chỉ được điề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 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 đủ điều kiện đã đị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 áp dụng được.

    Bước di chuyển: Cập nhật PurchasesUpdatedListener hoặc cách xử lý kết quả tương đương để nhận ra 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 tốt hơn cho người dùng. Ví dụ: nhắc người dùng khắc phục phương thức thanh toán hoặc hiển thị một thông báo lỗi cụ thể.

  6. Nhận thức về việc phân loại lại mã lỗi.

    Đối với những trường hợp ứng dụng Cửa hàng Play bị hệ thống chặn (ví dụ: trong chế độ dành cho trẻ em do OEM tuỳ chỉnh), 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 phù hợp với thay đổi này và không dựa vào việc nhận lỗi chung trong các trường hợp cụ thể này.

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

    Nếu bạn sử dụng DeveloperProvidedBillingDetails trong quá trình tích hợp hệ thống 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à 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 ý định của trình duyệt. Ví dụ:

    Kotlin

    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. Các thay đổi không bắt buộc.