Hướng dẫn di chuyển Thư viện Google Play Billing 4 sang 5

Chủ đề này mô tả cách di chuyển từ Thư viện Google Play Billing 4 sang Thư viện Google Play Billing 5 và cách sử dụng các tính năng thuê bao mới.

Tổng quan

Thư viện Google Play Billing phiên bản 5 giới thiệu các ưu đãi trong gói thuê bao và gói cơ bản trong gói thuê bao. Các tính năng này mở rộng cách thức bạn có thể bán gói thuê bao, giảm chi phí hoạt động bằng cách loại bỏ nhu cầu tạo và quản lý số lượng SKU không ngừng tăng. Để biết thêm thông tin, hãy xem Các thay đổi gần đây đối với Gói thuê bao trong Play Console.

Tất cả sản phẩm thuê bao hiện tại đã được tự động chuyển đổi sang mô hình mới này trong bản phát hành tháng 5 năm 2022 của Thư viện Play Billing 5 và nền tảng mới cho gói thuê bao. Để tìm hiểu thêm thông tin về quá trình chuyển đổi này, hãy xem phần Xử lý gói thuê bao cũ trong bài viết trên trang Play Console Trợ giúp.

Bằng cách sử dụng API Play Developer Console hoặc API Nhà phát triển Play, bạn hiện có thể thiết lập một gói thuê bao với nhiều gói cơ bản, mỗi gói có nhiều ưu đãi. Các gói ưu đãi có mô hình định giá và cách thiết lập tính đủ điều kiện một cách linh hoạt. Bạn có thể tạo chương trình ưu đãi trong suốt vòng đời của gói thuê bao bằng cách sử dụng nhiều gói tự động gia hạn và trả trước. Để biết thêm thông tin, hãy xem hướng dẫn tích hợp.

Tuy nhiên, nếu không có kế hoạch áp dụng các tính năng mới này ngay lập tức, thì sau này bạn vẫn có thể di chuyển ứng dụng của mình sang Thư viện Play Billing 5 và lên kế hoạch di chuyển các thành phần phụ trợ, miễn là danh sách sản phẩm của bạn nằm trong một cấu hình có khả năng tương thích ngược.

Các bước di chuyển

Tạo danh sách sản phẩm phụ trợ

Bạn nên tạo sản phẩm mới theo cấu trúc thực thể trong nền tảng mới cho gói thuê bao để tích hợp Thư viện Play Billing 5 trước khi di chuyển ứng dụng. Bạn có thể hợp nhất các sản phẩm trùng lặp trong danh mục cũ có cùng lợi ích về quyền trong một gói thuê bao, đồng thời sử dụng các cấu hình của ưu đãi và gói cơ bản để đại diện cho tất cả các lựa chọn mà bạn muốn cung cấp. Để biết thêm thông tin về đề xuất này, hãy xem phần Xử lý gói thuê bao cũ trong bài viết trên trang Play Console Trợ giúp.

Bạn không nên sửa đổi các sản phẩm thuê bao đã chuyển đổi sau bản phát hành tháng 5 năm 2022 mà nên giữ nguyên sản phẩm để bán kèm theo những phiên bản ứng dụng sử dụng các phương thức không dùng nữa (ví dụ: querySkuDetailsAsync()) nhưng không áp dụng các thay đổi có thể ảnh hưởng đến các bản dựng cũ này.

Quá trình chuyển đổi khiến các sản phẩm thuê bao trong danh mục của bạn trước tháng 5 năm 2022 ở chế độ chỉ có thể đọc để tránh những thay đổi do nhầm lẫn. Đây là những thay đổi có khả năng dẫn đến các vấn đề với chức năng tích hợp hiện có. Bạn có thể thực hiện các thay đổi đối với những gói thuê bao này, nhưng sẽ có những tác động có thể ảnh hưởng đến giao diện người dùng và các chức năng tích hợp phụ trợ:

  • Trên giao diện người dùng, các phiên bản ứng dụng dùng querySkuDetailsAsync() để lấy thông tin chi tiết về sản phẩm thuê bao chỉ có thể bán các ưu đãi và gói cơ bản có khả năng tương thích ngược. Đồng thời, do chỉ có một cách kết hợp giữa ưu đãi và gói cơ bản có khả năng tương thích ngược, nên nếu bạn thêm các ưu đãi hoặc gói mới vào gói thuê bao đã chuyển đổi, thì các phiên bản cũ này của ứng dụng sẽ không bán được các ưu đãi hoặc gói cơ bản bổ sung mới.

  • Trên phần phụ trợ, nếu chỉnh sửa các gói thuê bao đã chuyển đổi trong giao diện người dùng Play Console, bạn sẽ không thể quản lý các gói thuê bao đó bằng điểm cuối inappproducts nếu đang gọi điểm cuối cho mục đích này. Bạn cũng nên chuyển sang điểm cuối mới của trạng thái mua gói thuê bao (purchases.subscriptionsv2.get) để quản lý các giao dịch mua những gói thuê bao này, bởi vì điểm cuối cũ của trạng thái mua (purchases.subscriptions.get) chỉ trả về dữ liệu cần thiết để xử lý các giao dịch mua ưu đãi và gói cơ bản có khả năng tương thích ngược. Hãy đọc phần Quản lý trạng thái mua gói thuê bao để biết thêm thông tin.

Quản lý danh mục gói thuê bao phụ trợ bằng API mới

Nếu tự động quản lý danh mục sản phẩm thuê bao của mình bằng API Nhà phát triển Google Play, bạn cần sử dụng các điểm cuối mới giúp xác định sản phẩm thuê bao để tạo và quản lý các gói thuê bao, gói cơ bản và ưu đãi. Hãy đọc Hướng dẫn về các tính năng của gói thuê bao tháng 5 năm 2022 để tìm hiểu thêm về những thay đổi đối với API danh mục sản phẩm của bản phát hành này.

Để di chuyển mô-đun tự động giúp quản lý danh mục sản phẩm cho gói thuê bao Google Play Billing, hãy thay thế API inappproducts bằng Subscription Publishing API (API phát hành gói thuê bao) mới để quản lý và phát hành danh mục gói thuê bao của bạn. Có 3 điểm cuối mới:

Các điểm cuối mới này có tất cả chức năng cần thiết để tận dụng mọi tính năng mới trong danh mục của bạn: gói cơ bản và thẻ ưu đãi, tính năng nhắm mục tiêu theo vùng, gói trả trước, v.v..

Bạn vẫn nên sử dụng API inappproducts để quản lý danh mục sản phẩm trong ứng dụng cho các sản phẩm áp dụng hình thức mua hàng một lần.

.

Các phiên bản ứng dụng sử dụng phương thức không dùng nữa (ví dụ: querySkuDetailsAsync()) sẽ không thể bán bất kỳ ưu đãi hoặc gói cơ bản nào không có khả năng tương thích ngược. Bạn có thể đọc về các ưu đãi có khả năng tương thích ngược tại đây.

Cập nhật Thư viện Google Play Billing

Sau khi tạo danh mục mới cho sản phẩm thuê bao, bạn có thể di chuyển ứng dụng của mình sang Thư viện Google Billing 5. Thay thế phần phụ thuộc hiện có của Thư viện Play Billing bằng phiên bản cập nhật cho tệp build.gradle của ứng dụng.

dependencies {
    def billingVersion = "5.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

Dự án của bạn sẽ được tạo ngay lập tức, ngay cả khi bạn chưa sửa đổi bất kỳ lệnh gọi nào đối với các phương thức, vì chúng tôi đã xây dựng khả năng tương thích ngược trên Thư viện Play Billing 5. Tuy nhiên, khái niệm SKU được coi là không dùng nữa.

Khởi tạo Ứng dụng thanh toán và thiết lập kết nối với Google Play

Các bước đầu tiên để tạo giao dịch mua từ một ứng dụng Android không thay đổi:

Hiển thị những sản phẩm có thể mua

Cách nhận tất cả ưu đãi người dùng đủ điều kiện để mua:

  • Thay thế SkuDetailsParams bằng QueryProductDetailsParams.
  • Chuyển lệnh gọi BillingClient.querySkuDetailsAsync() để sử dụng BillingClient.queryProductDetailsAsync()

Lưu ý kết quả truy vấn giờ đây sẽ là ProductDetails thay vì SkuDetails. Mỗi mặt hàng ProductDetails chứa thông tin về sản phẩm (mã nhận dạng, tiêu đề, loại, v.v.). Đối với các sản phẩm thuê bao, ProductDetails chứa List<ProductDetails.SubscriptionOfferDetails>, là danh sách thông tin chi tiết về ưu đãi cho thuê bao. Đối với các sản phẩm mua một lần, ProductDetails chứa ProductDetails.OneTimePurchaseOfferDetails. Bạn có thể dùng thông tin này để quyết định ưu đãi nào sẽ hiển thị cho người dùng.

Ví dụ sau cho thấy ứng dụng của bạn trông như thế nào trước và sau khi thực hiện những thay đổi này:

Trước

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS)

billingClient.querySkuDetailsAsync(params.build()) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS);

billingClient.querySkuDetailsAsync(params.build(),
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Sau

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList)

billingClient.queryProductDetailsAsync(params.build()) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

Lệnh gọi lại cho queryProductDetailsAsync trả về List<ProductDetails>. Mỗi mặt hàng ProductDetails chứa thông tin về sản phẩm (mã nhận dạng, tiêu đề, loại, v.v.). Điểm khác biệt chính là các sản phẩm thuê bao hiện cũng chứa List<ProductDetails.SubscriptionOfferDetails> chứa tất cả các ưu đãi người dùng có thể sử dụng.

Vì các phiên bản trước của Thư viện Play Billing không hỗ trợ các đối tượng mới (gói thuê bao, gói cơ bản, ưu đãi, v.v.), nên hệ thống mới sẽ chuyển đổi từng SKU thuê bao thành một ưu đãi và gói cơ bản có khả năng tương thích ngược. Các sản phẩm mua một lần cũng được chuyển đến đối tượng ProductDetails. Bạn có thể truy cập thông tin chi tiết về ưu đãi của một sản phẩm mua một lần bằng phương thức getOneTimePurchaseOfferDetails().

Trong một số ít trường hợp, một số thiết bị không hỗ trợ ProductDetails và queryProductDetailsAsync(), thường là do các phiên bản Dịch vụ Google Play đã lỗi thời. Để đảm bảo nhận được sự hỗ trợ phù hợp cho trường hợp này, hãy gọi isFeatureSupported() cho tính năng PRODUCT_DETAILS trước khi gọi queryProductDetailsAsync. Nếu phản hồi là OK, thiết bị sẽ hỗ trợ tính năng này và bạn có thể tiếp tục gọi queryProductDetailsAsync(). Nếu phản hồi là FEATURE_NOT_SUPPORTED, bạn có thể dùng querySkuDetailsAsync() để yêu cầu danh sách sản phẩm có khả năng tương thích ngược. Để tìm hiểu thêm về cách sử dụng tính năng tương thích ngược của Thư viện Play Billing 5, hãy xem Hướng dẫn cho các tính năng thuê bao – Tháng 5 năm 2022.

Ra mắt quy trình mua ưu đãi

Việc bắt đầu một quy trình mua hàng cho một ưu đãi rất giống với việc ra mắt một quy trình cho SKU. Để bắt đầu một yêu cầu mua hàng bằng phiên bản 5, hãy làm như sau:

  • Thay vì dùng SkuDetails cho BillingFlowParams, hãy dùng ProductDetailsParams.
  • Bạn có thể lấy thông tin chi tiết về (các) ưu đãi, chẳng hạn như mã ưu đãi, mã gói cơ bản và các thông tin khác thông qua đối tượng SubscriptionOfferDetails.

Để mua sản phẩm bằng ưu đãi đã chọn của người dùng, hãy lấy offerToken của ưu đãi đã chọn và truyền ưu đãi đó vào đối tượng ProductDetailsParams.

Sau khi bạn tạo đối tượng BillingFlowParams, việc chạy luồng thanh toán với BillingClient vẫn giữ nguyên.

Ví dụ sau cho bạn thấy ứng dụng sẽ trông như thế nào trước và sau khi thực hiện các thay đổi này:

Trước

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Sau

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(productDetailsParamsList)
            .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Xử lý các giao dịch mua

Việc xử lý các giao dịch mua bằng Thư viện Google Play Billing 5 vẫn tương tự như các phiên bản trước.

Để lấy tất cả các giao dịch mua đang hoạt động thuộc sở hữu của người dùng và truy vấn các giao dịch mua mới, hãy làm như sau:

  • Thay vì chuyển giá trị BillingClient.SkuType đến queryPurchasesAsync(), hãy chuyển đối tượng QueryPurchasesParams chứa giá trị BillingClient.ProductType.

Ví dụ sau cho bạn thấy ứng dụng sẽ trông như thế nào trước và sau khi thực hiện các thay đổi này:

Trước

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java


billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Sau

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

Các bước để quản lý giao dịch mua ngoài ứng dụng và giao dịch đang chờ xử lý không thay đổi.

Quản lý trạng thái giao dịch mua gói thuê bao bằng API mới trong phần phụ trợ

Bạn nên di chuyển thành phần quản lý trạng thái của giao dịch mua gói thuê bao trong phần phụ trợ để sẵn sàng xử lý các giao dịch mua sản phẩm mới đã tạo ở các bước trước. Thành phần quản lý trạng thái của giao dịch mua gói thuê bao hiện tại sẽ hoạt động như bình thường đối với các sản phẩm thuê bao đã chuyển đổi mà bạn xác định trước thời điểm ra mắt tháng 5 năm 2022, và gói thuê bao cần có đủ điều kiện để quản lý các giao dịch mua ưu đãi có khả năng tương thích ngược nhưng không hỗ trợ bất kỳ chức năng mới nào.

Bạn cần triển khai Subscription Purchases API (API Giao dịch mua gói thuê bao) mới cho mô-đun quản lý trạng thái của giao dịch mua của các gói thuê bao. Mô-đun này kiểm tra trạng thái của giao dịch mua và quản lý các quyền của gói thuê bao Play Billing trong phần phụ trợ. Phiên bản cũ của API không trả về tất cả thông tin chi tiết cần thiết để quản lý các giao dịch mua trong nền tảng mới. Để biết thông tin chi tiết về những thay đổi so với các phiên bản trước, hãy xem hướng dẫn cho các tính năng mới của gói thuê bao trong tháng 5 năm 2022.

Thông thường, bạn sẽ gọi Subscription Purchases API (API Giao dịch mua gói thuê bao) mỗi khi nhận được Thông báo theo thời gian thực dành cho nhà phát triển SubscriptionNotification để lấy thông tin mới nhất về trạng thái của gói thuê bao. Bạn cần thay thế các lệnh gọi đến purchases.subscriptions.get bằng phiên bản mới của Subscription Purchases API (API Giao dịch mua gói thuê bao), purchases.subscriptionsv2.get. Có một tài nguyên mới tên là SubscriptionPurchaseV2. Tài nguyên này cung cấp đầy đủ thông tin để quản lý quyền mua các gói thuê bao trong mô hình mới.

Điểm cuối mới này trả về trạng thái của tất cả các sản phẩm thuê bao và giao dịch mua của bạn, bất kể phiên bản ứng dụng đã bán sản phẩm và thời điểm sản phẩm được xác định (trước hoặc sau bản phát hành tháng 5 năm 2022). Vì vậy, sau khi di chuyển, bạn chỉ cần dùng phiên bản này của mô-đun quản lý trạng thái của giao dịch mua gói thuê bao.