Panduan Migrasi Library Layanan Penagihan Google Play 4 ke 5

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

Catatan: Topik ini menyoroti perubahan paling penting yang diperlukan untuk melakukan upgrade. Untuk langkah-langkah mendetail tentang integrasi, lihat langkah demi langkah panduan integrasi beserta cuplikan kode dalam contoh khusus penagihan yang dihosting di GitHub.

Ringkasan

Library Layanan Penagihan Google Play 5 memperkenalkan paket dasar langganan dan penawaran langganan. Fitur ini memberikan cara baru untuk menjual langganan, sehingga mengurangi biaya operasional dengan meniadakan kebutuhan untuk membuat dan mengelola jumlah SKU yang semakin meningkat. Untuk informasi selengkapnya, lihat Perubahan terbaru terkait Langganan di Konsol Play.

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. Untuk membaca informasi selengkapnya tentang konversi ini, lihat bagian Mengelola langganan lama di Artikel bantuan Konsol Play.

Dengan menggunakan Konsol Play atau Play Developer API, 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 perpanjangan otomatis dan paket prabayar. Untuk informasi selengkapnya, lihat panduan integrasi.

Namun, jika tidak berencana untuk langsung menggunakan fitur baru ini, Anda masih dapat memigrasikan aplikasi ke Library Layanan Penagihan Play 5 dan merencanakan migrasi komponen backend nanti, selama katalog produk Anda tetap dalam konfigurasi yang kompatibel dengan versi sebelumnya.

Langkah Migrasi

Membuat katalog produk backend

Sebaiknya buat produk baru mengikuti struktur entity di platform langganan baru untuk integrasi Library Layanan Penagihan Play 5 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 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 sebelumnya, dan hanya boleh ada satu paket dasar dan kombinasi penawaran yang kompatibel dengan versi sebelumnya. 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 Anda 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 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 = "5.0.0"

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

Project Anda akan langsung di-build, meskipun Anda belum mengubah panggilan apa pun ke metode, karena kami telah mem-build kompatibilitas mundur di Library Layanan Penagihan Play 5. Namun, konsep SKU dianggap tidak digunakan lagi.

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)

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

Setelah

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

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 sebelumnya. 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 Library Layanan Penagihan Play 5, 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 5, 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 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 = ...;
// 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);

Memproses pembelian

Pemrosesan pembelian menggunakan Library Layanan Penagihan Google Play 5 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.

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 sebelumnya, 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.