Bermigrasi ke Google Play Billing Library 6 dari versi 4 atau 5

Topik ini menjelaskan cara melakukan migrasi dari Library Layanan Penagihan Google Play 4 atau 5 ke Library Layanan Penagihan Google Play 6 dan cara menggunakan kemampuan langganan baru.

Untuk daftar lengkap perubahan pada versi 6.0.0, lihat catatan rilis.

Ringkasan

Library Layanan Penagihan Google Play 6 dibuat berdasarkan fitur langganan baru yang diperkenalkan di versi 5 dan menambahkan beberapa peningkatan lainnya. Fitur ini memungkinkan Anda menjual langganan dengan lebih banyak cara, sehingga mengurangi biaya operasional dengan meniadakan kebutuhan untuk membuat dan mengelola SKU yang jumlahnya terus meningkat.

Untuk mengetahui informasi selengkapnya tentang fitur baru yang diperkenalkan di Library Layanan Penagihan Play 5, lihat Perubahan terbaru terkait langganan di Konsol Play.

Upgrade Play Billing Library yang kompatibel dengan versi lama

Semua produk langganan yang ada otomatis dikonversi ke paradigma baru ini sebagai bagian dari rilis Library Layanan Penagihan Play 5 dan platform langganan baru pada Mei 2022. Artinya, Anda tidak perlu membuat perubahan konfigurasi produk langganan untuk memiliki katalog yang kompatibel dengan versi baru Library Layanan Penagihan Play. Untuk mengetahui informasi selengkapnya tentang bagaimana SKU langganan dikonversi menjadi langganan yang kompatibel dengan versi lama, lihat bagian Mengelola langganan lama di Artikel bantuan Konsol Play.

Versi lama aplikasi Anda masih berfungsi

Jika Anda memiliki katalog langganan yang kompatibel dengan versi lama, semua versi aplikasi yang ada harus tetap berfungsi sebagaimana mestinya untuk produk tersebut. Pembelian produk sekali beli juga harus terus berfungsi tanpa masalah pada versi yang lebih lama.

Versi aplikasi Anda yang menggunakan metode yang tidak digunakan lagi (misalnya, querySkuDetailsAsync()) tidak akan dapat menjual paket dasar atau penawaran yang tidak kompatibel dengan versi lama. Anda dapat membaca tentang penawaran yang kompatibel dengan versi lama di artikel Pusat Bantuan Konsol Play yang relevan.

Mengupgrade ke Play Billing Library 5 atau 6

Library Layanan Penagihan Play 5 dan 6 menyertakan metode querySkuDetailsAsync dan BillingFlowParams.Builder.setSkuDetails yang tidak digunakan lagi dan menggunakan SkuDetails sebagai parameter alur penagihan. Hal ini berarti Anda dapat secara bertahap beralih ke Library Layanan Penagihan Play 6 dengan merencanakan berbagai tahap migrasi.

Sebagai langkah pertama untuk migrasi, Anda dapat mengupdate versi library, membiarkan katalog dan backend sebagaimana adanya, serta menguji aplikasi Anda saat masih menggunakan metode yang tidak digunakan lagi. Jika Anda tidak menggunakan queryPurchases, launchPriceChangeFlow, atau setVrPurchaseFlow, seharusnya aplikasi masih berfungsi sebagaimana mestinya. Setelah itu, Anda dapat melakukan iterasi untuk mengadopsi sepenuhnya fitur langganan baru yang dirilis pada Mei 2022.

Jika sebelumnya Anda telah mengadopsi fitur ini dengan migrasi Library Layanan Penagihan Google Play 5, Anda dapat langsung melanjutkan ke bagian yang berlabel Mengupdate Library Layanan Penagihan Google Play dan Mengubah pembelian langganan pengguna. Jika Anda memulai dari versi sebelumnya atau belum sepenuhnya mengadopsi fitur baru, Anda dapat membaca langkah-langkah migrasi lengkap untuk mempelajari cara mengadopsinya.

Langkah-langkah migrasi lengkap

Membuat langganan baru di katalog produk backend

Dengan menggunakan Konsol Play atau API Developer Play, Anda kini dapat mengonfigurasi satu langganan dengan beberapa paket dasar, masing-masing dengan beberapa penawaran. Penawaran langganan memiliki model harga dan opsi kelayakan yang fleksibel. Anda dapat membuat penawaran di seluruh siklus proses langganan menggunakan berbagai paket prabayar dan paket perpanjangan otomatis.

Sebaiknya buat produk baru mengikuti struktur entity di platform langganan baru untuk integrasi Library Layanan Penagihan Play 6 Anda sebelum memigrasikan aplikasi. Anda dapat menggabungkan produk duplikat di katalog lama yang mewakili manfaat hak yang sama dalam satu langganan, serta menggunakan paket dasar dan konfigurasi penawaran untuk menunjukkan semua opsi yang ingin Anda tawarkan. Untuk mengetahui informasi selengkapnya tentang rekomendasi ini, lihat bagian Mengelola langganan lama di Artikel bantuan Konsol Play.

Sebaiknya jangan ubah produk langganan yang dikonversi setelah rilis Mei 2022. Anda harus membiarkannya seperti yang dijual dengan versi aplikasi yang menggunakan metode yang tidak digunakan lagi (misalnya, querySkuDetailsAsync()) tanpa memperkenalkan perubahan yang dapat memengaruhi versi lama ini.

Proses konversi membuat produk langganan yang ada di katalog Anda sebelum Mei 2022 menjadi hanya baca untuk menghindari perubahan tidak disengaja yang dapat mengakibatkan masalah dengan integrasi yang sudah ada. Anda dapat melakukan perubahan pada langganan ini, tetapi akan ada implikasi yang dapat memengaruhi integrasi frontend dan backend Anda:

• Pada frontend, versi aplikasi yang menggunakan querySkuDetailsAsync() untuk mendapatkan detail produk langganan hanya dapat menjual paket dasar dan penawaran yang kompatibel dengan versi lama, dan hanya boleh ada satu paket dasar dan kombinasi penawaran yang kompatibel dengan versi lama. Jadi, jika Anda menambahkan paket atau penawaran baru ke langganan yang dikonversi, penawaran atau paket dasar tambahan tersebut tidak akan dapat dijual pada versi lama aplikasi.

• Di backend, jika mengedit langganan yang dikonversi di UI Konsol Play, Anda tidak akan dapat mengelolanya dengan endpoint inappproducts, jika Anda memanggil endpoint untuk tujuan ini. Anda juga harus bermigrasi ke endpoint status pembelian langganan baru (purchases.subscriptionsv2.get) untuk mengelola pembelian langganan ini, karena endpoint status pembelian lama (purchases.subscriptions.get) hanya menampilkan data yang diperlukan untuk menangani pembelian paket dasar dan penawaran yang kompatibel dengan versi lama. Baca bagian Mengelola status pembelian langganan untuk mengetahui informasi selengkapnya.

Mengelola katalog langganan backend dengan API baru

Jika Anda mengelola katalog produk langganan secara otomatis dengan Google Play Developer API, Anda harus menggunakan endpoint definisi produk langganan baru untuk membuat dan mengelola langganan, paket dasar, dan penawaran. Baca panduan fitur langganan Mei 2022 untuk mempelajari lebih lanjut perubahan API katalog produk untuk rilis ini.

Untuk memigrasikan modul pengelolaan katalog produk otomatis bagi langganan Layanan Penagihan Google Play, ganti inappproducts API dengan Subscription Publishing API baru untuk mengelola dan memublikasikan katalog langganan Anda. Ada tiga endpoint baru:

• Monetization.subscriptions untuk mengelola produk langganan.
• Monetization.basePlans untuk mengelola paket dasar langganan.
• Monetization.offers untuk mengelola penawaran paket dasar.

Endpoint baru ini memiliki semua fungsi yang diperlukan untuk memanfaatkan semua kemampuan baru di katalog Anda: tag paket dasar dan penawaran, penargetan wilayah, paket prabayar, dan lainnya.

Anda tetap harus menggunakan inappproducts API untuk mengelola katalog produk dalam aplikasi untuk produk pembelian satu kali.

Catatan: inappproducts API untuk pengelolaan produk akan terus menampilkan detail produk langganan seperti sebelumnya untuk langganan yang dikonversi jika Anda belum menyetelnya agar dapat diedit di Konsol Play. Setelah Anda mulai mengedit langganan di Konsol, inappproducts API tidak dapat lagi digunakan untuk langganan.

Versi aplikasi Anda yang menggunakan metode yang tidak digunakan lagi (misalnya, querySkuDetailsAsync()) tidak akan dapat menjual paket dasar atau penawaran yang tidak kompatibel dengan versi lama. Anda dapat membaca penawaran yang kompatibel dengan versi lama di sini.

Mengupdate Library Layanan Penagihan Google Play

Setelah membuat katalog produk langganan baru, Anda dapat memigrasikan aplikasi ke Library Penagihan Google 5. Ganti dependensi Library Layanan Penagihan Play yang ada dengan versi yang sudah diupdate ke file build.gradle aplikasi Anda.

dependencies {
    def billingVersion = "6.0.0"

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

Project Anda akan langsung di-build, meskipun Anda belum mengubah panggilan apa pun ke metode—Library Layanan Penagihan Play 6 kompatibel dengan versi lama. Konsep SKU dianggap tidak digunakan lagi, tetapi masih ada untuk membuat proses transfer aplikasi menjadi lebih sederhana dan lebih inkremental.

Catatan: Jika bermigrasi dari Library Layanan Penagihan Play 5, Anda dapat langsung ke bagian Mengubah pembelian langganan pengguna.

Melakukan inisialisasi pada Klien Penagihan dan membuat koneksi ke Google Play

Langkah pertama untuk meluncurkan pembelian dari aplikasi Android tetap sama:

• Melakukan Inisialisasi pada Klien Penagihan
• Membuat koneksi ke Google Play

Menampilkan produk yang tersedia untuk dibeli

Untuk mendapatkan semua penawaran yang dapat dibeli oleh pengguna yang memenuhi syarat:

• Ganti SkuDetailsParams dengan QueryProductDetailsParams
• Ganti panggilan BillingClient.querySkuDetailsAsync() untuk menggunakan BillingClient.queryProductDetailsAsync()

Perhatikan bahwa hasil kueri sekarang adalah ProductDetails, bukan SkuDetails. Setiap item ProductDetails berisi informasi tentang produk (ID, judul, jenis, dan sebagainya). Untuk produk langganan, ProductDetails berisi List<ProductDetails.SubscriptionOfferDetails>, yang merupakan daftar detail penawaran langganan. Untuk produk pembelian satu kali, ProductDetails berisi ProductDetails.OneTimePurchaseOfferDetails. Ini dapat digunakan untuk memutuskan penawaran mana yang akan ditampilkan kepada pengguna.

Contoh berikut menunjukkan contoh tampilan aplikasi Anda sebelum dan sesudah perubahan dilakukan:

Sebelum

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

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

billingClient.querySkuDetailsAsync(params) {
    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).build();

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

Setelah

Kotlin

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

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

billingClient.queryProductDetailsAsync(params) {
    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
                }
        }
);

Callback untuk queryProductDetailsAsync akan menampilkan List<ProductDetails>. Setiap item ProductDetails berisi informasi tentang produk (ID, judul, jenis, dan sebagainya). Perbedaan utamanya adalah produk langganan kini juga berisi List<ProductDetails.SubscriptionOfferDetails> yang memuat semua penawaran yang tersedia untuk pengguna.

Karena Library Layanan Penagihan Play versi sebelumnya tidak mendukung objek baru (langganan, paket dasar, penawaran, dan sebagainya), sistem baru menerjemahkan setiap SKU langganan ke dalam satu paket dasar dan penawaran yang kompatibel dengan versi lama. Produk pembelian satu kali yang tersedia juga ditransfer ke objek ProductDetails. Detail penawaran produk pembelian satu kali dapat diakses dengan metode getOneTimePurchaseOfferDetails().

Beberapa perangkat jarang sekali tidak dapat mendukung ProductDetails dan queryProductDetailsAsync(), biasanya karena versi Layanan Google Play yang sudah tidak berlaku. Untuk memastikan dukungan yang tepat untuk skenario ini, panggil isFeatureSupported() untuk fitur PRODUCT_DETAILS sebelum memanggil queryProductDetailsAsync. Jika responsnya adalah OK, perangkat akan mendukung fitur tersebut dan Anda dapat melanjutkan dengan memanggil queryProductDetailsAsync(). Jika responsnya adalah FEATURE_NOT_SUPPORTED, Anda dapat meminta daftar produk yang kompatibel dengan versi lama yang tersedia menggunakan querySkuDetailsAsync(). Untuk mempelajari lebih lanjut cara menggunakan fitur kompatibilitas mundur, lihat Panduan fitur langganan Mei 2022.

Meluncurkan alur pembelian penawaran

Meluncurkan alur pembelian untuk penawaran sangat mirip dengan meluncurkan alur untuk SKU. Untuk memulai permintaan pembelian menggunakan versi 6, lakukan hal berikut:

• Gunakan ProductDetailsParams, bukan SkuDetails untuk BillingFlowParams.
• Detail penawaran, seperti ID penawaran, ID paket dasar, dan lainnya dapat diperoleh menggunakan objek SubscriptionOfferDetails.

Untuk membeli produk dengan penawaran yang dipilih pengguna, dapatkan offerToken penawaran yang dipilih dan teruskan ke objek ProductDetailsParams.

Setelah Anda membuat objek BillingFlowParams, peluncuran alur penagihan dengan BillingClient akan tetap sama.

Contoh berikut menunjukkan contoh tampilan aplikasi Anda sebelum dan sesudah perubahan dilakukan:

Sebelum

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)

Setelah

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

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

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

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

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

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

Memproses pembelian

Pemrosesan pembelian menggunakan Library Layanan Penagihan Google Play 6 akan tetap sama dengan versi sebelumnya.

Untuk menarik semua pembelian aktif yang dimiliki oleh pengguna dan membuat kueri untuk pembelian baru, lakukan langkah berikut:

• Alih-alih meneruskan nilai BillingClient.SkuType ke queryPurchasesAsync(), teruskan objek QueryPurchasesParams yang berisi nilai BillingClient.ProductType.

Catatan: Jika Anda bermigrasi dari versi 4, perhatikan bahwa metode queryPurchases sebelumnya yang tidak digunakan lagi telah dihapus di Library Layanan Penagihan Play Koleksi 6. Gunakan queryPurchasesAsync seperti ditunjukkan di bawah ini.

Contoh berikut menunjukkan tampilan aplikasi Anda sebelum dan sesudah perubahan dilakukan:

Sebelum

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
        }
    }
);

Setelah

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
        }
    }
);

Langkah-langkah untuk mengelola pembelian di luar aplikasi dan transaksi yang tertunda belum berubah.

Mengelola status pembelian langganan dengan API baru di backend

Anda harus memigrasikan komponen pengelolaan status langganan di backend agar siap menangani pembelian produk baru yang dibuat pada langkah sebelumnya. Komponen pengelolaan status pembelian langganan Anda saat ini akan berfungsi seperti biasa untuk produk langganan yang dikonversi yang Anda tentukan sebelum peluncuran Mei 2022, dan sudah cukup untuk mengelola pembelian penawaran yang kompatibel dengan versi lama, tetapi tidak mendukung fungsi baru.

Anda perlu menerapkan Subscription Purchases API baru untuk modul pengelolaan status pembelian langganan, yang memeriksa status pembelian dan mengelola hak langganan Layanan Penagihan Play di backend. Versi lama API tidak menampilkan semua detail yang diperlukan untuk mengelola pembelian di platform baru. Untuk mengetahui detail tentang perubahan dari versi sebelumnya, lihat panduan untuk fitur langganan baru bulan Mei 2022.

Anda biasanya akan memanggil Subscription Purchases API setiap kali Anda menerima Notifikasi Developer Real Time SubscriptionNotification untuk mengambil informasi terbaru tentang status langganan. Anda harus mengganti panggilan ke purchases.subscriptions.get dengan versi baru Subscription Purchases API, purchases.subscriptionsv2.get. Tersedia resource baru bernama SubscriptionPurchaseV2 yang memberikan cukup informasi untuk mengelola hak pembelian untuk langganan dalam model baru.

Endpoint baru ini menampilkan status untuk semua produk langganan Anda dan semua pembelian Anda, terlepas dari versi aplikasi yang menjualnya dan kapan produk tersebut ditentukan (sebelum atau setelah rilis Mei 2022). Jadi, setelah migrasi, Anda hanya memerlukan versi modul pengelolaan status pembelian langganan ini.

Mengubah pembelian langganan pengguna

Di Library Layanan Penagihan Play 5 dan yang lebih lama, ProrationMode digunakan untuk menerapkan perubahan pada pembelian langganan pengguna, seperti upgrade atau downgrade. Proses ini tidak digunakan lagi dan diganti dengan ReplacementMode dalam versi 6.

Menangani perubahan harga langganan

launchPriceConfirmationFlow API sebelumnya yang tidak digunakan lagi telah dihapus di Library Layanan Penagihan Play 6. Untuk alternatifnya, lihat panduan perubahan harga.

Menangani error Play Billing Library

Di Library Layanan Penagihan Play 6, kode NETWORK_ERROR baru telah ditambahkan untuk menunjukkan masalah dengan koneksi jaringan antara perangkat pengguna dan sistem Google Play. Ada juga perubahan pada kode SERVICE_TIMEOUT dan SERVICE_UNAVAILABLE. Untuk mengetahui informasi selengkapnya, lihat Menangani kode respons BillingResult.

Menangani transaksi yang tertunda

Mulai versi 6.0.0, Library Layanan Penagihan Play tidak membuat ID pesanan untuk pembelian yang tertunda. Untuk pembelian ini, ID pesanan diisi setelah pembelian dipindahkan ke status PURCHASED. Pastikan integrasi Anda hanya mengharapkan ID pesanan setelah transaksi selesai sepenuhnya. Anda tetap dapat menggunakan token pembelian untuk data Anda. Untuk mengetahui informasi selengkapnya tentang cara menangani pembelian yang tertunda, lihat panduan integrasi dan panduan pengelolaan siklus proses pembelian Library Layanan Penagihan Play.