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 chứa các điểm cải tiến đối với API hiện có cùng với việc xoá các API không dùng nữa trước đây. 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ố tham chiếu 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 này 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 Google Play Billing Library 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 Google Play Billing Library. Để đư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 bản 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, yêu cầu 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ó thể mua.

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

    Bảng sau đây liệt kê các API đã 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 cách triển khai của bạn sử dụng bất kỳ API nào đã xoá này, hãy tham khảo bảng để biết các API thay thế tương ứng.

    API không dùng nữa trước đây đã bị xoá API thay thế để sử dụng
    API queryPurchaseHistoryAsync Xem phần Truy vấn nhật ký giao dịch mua. Nếu bạn đ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.
    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 đã 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.

    API không dùng nữa trước đây đã bị xoá 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ật tính năng tự động kết nối lại dịch vụ.

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

    BillingResult được trả về từ launchBillingFlow() sẽ bao gồm một trường mã phản hồi phụ. Trường này sẽ 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 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 đã định cấu hình cho ưu đãi gó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.

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

  6. Lưu ý về việc phân loại lại mã lỗi.

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