Panduan perubahan langganan Mei 2022

Sistem penagihan Google Play adalah layanan yang memungkinkan Anda menjual produk dan konten digital di aplikasi Android. Dengan rilis Mei 2022, kami telah mengubah cara produk langganan ditentukan, dan hal ini memengaruhi cara produk tersebut dijual di aplikasi dan dikelola di backend Anda. Jika Anda berintegrasi dengan Layanan Penagihan Google Play untuk pertama kalinya, Anda dapat memulai integrasi dengan membaca Penyiapan.

Jika Anda menjual langganan dengan Layanan Penagihan Google Play sebelum Mei 2022, penting untuk memahami cara menggunakan fitur-fitur baru sekaligus mempertahankan langganan yang ada.

Hal pertama yang perlu diketahui adalah semua langganan, aplikasi, dan integrasi backend yang sudah ada berfungsi seperti sebelum rilis Mei 2022. Anda tidak perlu membuat perubahan langsung, dan Anda dapat menggunakan fitur-fitur baru ini dari waktu ke waktu. Setiap rilis utama Library Layanan Penagihan Google Play didukung selama dua tahun setelah rilis. Integrasi yang ada dengan Google Play Developer API akan terus berfungsi seperti sebelumnya.

Berikut adalah ringkasan pembaruan pada bulan Mei 2022:

• Konsol Google Play baru memungkinkan Anda membuat dan mengelola langganan, paket dasar, dan penawaran. Hal ini mencakup langganan baru dan yang dimigrasikan.
• Play Developer API berisi update untuk mendukung fungsi UI Konsol Google Play baru dalam bentuk API. Secara khusus, ada versi baru Subscription Purchases API. Gunakan API ini untuk memeriksa status langganan dan mengelola pembelian langganan.
• Library Layanan Penagihan Play versi 5 yang baru memungkinkan aplikasi Anda mendapatkan manfaat dari semua fitur langganan baru. Jika Anda sudah siap melakukan upgrade ke versi 5, ikuti panduan di panduan migrasi.

Konfigurasi langganan

Mengelola langganan melalui Konsol Google Play

Mulai Mei 2022, Anda akan melihat beberapa perbedaan di Konsol Google Play.

Satu langganan kini dapat memiliki beberapa paket dasar dan penawaran. SKU langganan yang sebelumnya telah dibuat kini muncul di Konsol Play sebagai objek penawaran, paket dasar, dan langganan baru. Jika Anda belum melakukannya, lihat Perubahan terbaru pada langganan di Konsol Play untuk mengetahui deskripsi objek baru, termasuk fungsi dan konfigurasinya. Semua produk langganan yang sudah ada akan muncul di Konsol Google Play dalam format baru ini. Setiap SKU kini diwakili oleh objek langganan yang berisi satu paket dasar dan penawaran kompatibilitas mundur, jika berlaku.

Karena integrasi yang lebih lama mengharuskan setiap langganan menyertakan satu penawaran, yang diwakili oleh objek SkuDetails, setiap langganan dapat memiliki satu paket dasar atau penawaran yang kompatibel dengan versi sebelumnya. Penawaran atau paket dasar yang kompatibel dengan versi sebelumnya akan ditampilkan sebagai bagian dari SKU untuk aplikasi yang menggunakan metode querySkuDetailsAsync() yang sudah tidak digunakan lagi. Untuk informasi selengkapnya tentang cara mengonfigurasi dan mengelola penawaran yang kompatibel dengan versi sebelumnya, lihat Memahami langganan. Setelah aplikasi Anda hanya menggunakan queryProductDetailsAsync(), dan setelah tidak ada versi lama aplikasi Anda yang masih melakukan pembelian, Anda tidak perlu lagi menggunakan penawaran kompatibilitas mundur.

Mengelola langganan melalui Subscriptions Publishing API

Play Developer API berisi fungsi baru untuk pembelian langganan. inappproducts API untuk pengelolaan SKU terus berfungsi seperti sebelumnya, termasuk menangani produk pembelian satu kali dan langganan, sehingga Anda tidak perlu melakukan perubahan langsung apa pun untuk mempertahankan integrasi.

Namun, perlu diingat bahwa Konsol Google Play hanya menggunakan entity langganan baru. Setelah Anda mulai mengedit langganan di Konsol, inappproducts API tidak dapat lagi digunakan untuk langganan.

Jika Anda telah menggunakan Publishing API sebelum Mei 2022, untuk menghindari masalah, langganan yang sudah ada kini akan muncul sebagai hanya baca di Konsol Google Play. Jika mencoba melakukan perubahan, Anda mungkin mendapatkan peringatan yang menjelaskan batasan ini. Sebelum mengedit langganan lebih lanjut di Konsol, Anda harus memperbarui integrasi backend agar menggunakan endpoint Publikasi Langganan baru. Endpoint monetization.subscriptions, monetization.subscriptions.baseplans, dan monetization.subscriptions.offers baru memungkinkan Anda mengelola semua penawaran dan paket dasar yang tersedia. Anda dapat melihat cara berbagai kolom dipetakan dari entity InAppProduct ke objek baru di bagian monetization.subscriptions pada tabel berikut:

InAppProduct	Langganan
packageName	packageName
sku	productId
status	basePlans[0].state
prices	basePlans[0].regionalConfigs.price
listings	listingan
defaultPrice	Tidak ada padanan
subscriptionPeriod	basePlans[0].autoRenewingBasePlanType.billingPeriodDuration
trialPeriod	basePlans[0].offers[0].phases[0].regionalConfigs[0].free
gracePeriod	basePlans[0].autoRenewingBasePlanType.gracePeriodDuration
subscriptionTaxesAndComplianceSettings	taxAndComplianceSettings

Update API yang diperlukan ini hanya berlaku untuk Publishing API (pengelolaan SKU).

Perubahan Library Layanan Penagihan Play

Untuk mendukung migrasi bertahap, Library Layanan Penagihan Play menyertakan semua metode dan objek yang tersedia di versi sebelumnya. Objek dan fungsi SkuDetails seperti querySkuDetailsAsync() masih ada sehingga Anda dapat melakukan upgrade untuk menggunakan versi baru fungsi tanpa harus segera mengupdate kode langganan yang sudah ada. Anda juga dapat mengontrol penawaran mana yang tersedia melalui metode ini dengan menandainya sebagai kompatibel dengan versi sebelumnya.

Selain mempertahankan metode lama, Library Layanan Penagihan Play 5 kini menyertakan objek ProductDetails baru dan metode queryProductDetailsAsync() yang sesuai untuk menangani entitas dan fungsi baru. Produk dalam aplikasi yang sudah ada (pembelian satu kali dan habis pakai) kini juga didukung oleh ProductDetails.

Untuk langganan, ProductDetails.getSubscriptionOfferDetails() menampilkan daftar semua paket dasar dan penawaran yang dapat dibeli oleh pengguna yang memenuhi syarat. Artinya, Anda dapat mengakses semua paket dasar dan penawaran yang memenuhi syarat bagi pengguna, terlepas dari kompatibilitas mundur. getSubscriptionOfferDetails() menampilkan null untuk produk non-langganan. Untuk pembelian satu kali, Anda dapat menggunakan getOneTimePurchaseOfferDetails().

Library Layanan Penagihan Play 5 juga menyertakan metode baru maupun lama untuk meluncurkan alur pembelian. Jika objek BillingFlowParams yang diteruskan ke BillingClient.launchBillingFlow() dikonfigurasi menggunakan objek SkuDetails, sistem akan mengekstrak informasi penawaran untuk menjual dari paket dasar atau penawaran yang kompatibel dengan versi sebelumnya dan terkait dengan SKU. Jika objek BillingFlowParams yang diteruskan ke BillingClient.launchBillingFlow() dikonfigurasi menggunakan objek ProductDetailsParams yang menyertakan ProductDetails dan String yang mewakili token penawaran tertentu untuk penawaran yang dibeli, sistem kemudian akan menggunakan informasi tersebut untuk mengidentifikasi produk yang diperoleh pengguna.

queryPurchasesAsync() menampilkan semua pembelian yang dimiliki oleh pengguna. Untuk menunjukkan jenis produk yang diminta, Anda dapat meneruskan nilai BillingClient.SkuType, seperti dalam versi lama, atau objek QueryPurchasesParams yang berisi nilai BillingClient.ProductType yang mewakili entitas langganan baru.

Sebaiknya segera update aplikasi Anda ke library versi 5 sehingga Anda dapat mulai memanfaatkan fitur-fitur langganan baru.

Mengelola status langganan

Bagian ini menjelaskan perubahan utama pada komponen backend dari integrasi sistem penagihan Google Play yang perlu diimplementasikan untuk migrasi ke versi 5.

Notifikasi Developer Real Time

Dalam waktu dekat, objek SubscriptionNotification tidak akan lagi berisi subscriptionId. Jika Anda mengandalkan kolom ini untuk mengidentifikasi produk langganan, Anda harus mengupdate untuk mendapatkan informasi ini dari status langganan dengan menggunakan purchases.subscriptionv2:get setelah Anda menerima notifikasi. Setiap elemen SubscriptionPurchaseLineItem dalam koleksi lineItems yang ditampilkan sebagai bagian dari status pembelian akan menyertakan productId yang sesuai.

Subscriptions Purchases API: mendapatkan status langganan

Di Subscriptions Purchases API versi sebelumnya, Anda dapat membuat kueri status langganan dengan menggunakan purchases.subscriptions:get. Endpoint ini tidak berubah dan terus berfungsi untuk pembelian langganan yang kompatibel dengan versi sebelumnya. Endpoint ini tidak mendukung fungsi baru apa pun yang dirilis pada bulan Mei 2022.

Di versi baru Subscriptions Purchases API, gunakan purchases.subscriptionsv2:get untuk mendapatkan status pembelian langganan. API ini kompatibel dengan langganan yang dimigrasi, langganan baru (baik prabayar maupun perpanjangan otomatis), dan pembelian semua jenis. Anda dapat menggunakan endpoint ini untuk memeriksa status langganan saat menerima notifikasi. Objek yang ditampilkan, SubscriptionPurchaseV2, berisi kolom baru, tetapi masih menyertakan data lama yang diperlukan untuk terus mendukung langganan yang sudah ada.

Kolom SubscriptionPurchaseV2 untuk paket prabayar

Kolom baru telah ditambahkan untuk mendukung paket prabayar yang diperpanjang oleh pengguna, bukan diperpanjang secara otomatis. Semua kolom berlaku untuk paket prabayar seperti halnya untuk langganan yang diperpanjang secara otomatis, dengan pengecualian berikut:

• [New field] lineItems[0].prepaid_plan.allowExtendAfterTime: menunjukkan kapan pengguna akan diizinkan untuk membeli tambahan saldo lain untuk memperpanjang paket prabayar mereka, karena pengguna hanya diizinkan untuk memiliki satu tambahan saldo yang belum terpakai dalam satu waktu.
• [New field] SubscriptionState: menentukan status objek langganan. Untuk paket prabayar, nilai ini selalu berupa ACTIVE, PENDING, atau CANCELED.
• lineItems[0].expiryTime: Kolom ini selalu ada untuk paket prabayar.
• paused_state_context: Kolom ini tidak pernah ada, karena paket prabayar tidak dapat dijeda.
• lineItems[0].auto_renewing_plan: Tidak ada untuk paket prabayar.
• canceled_state_context: Tidak ada untuk paket prabayar, karena kolom ini hanya berlaku untuk pengguna yang secara aktif membatalkan langganan.
• lineItems[0].productId: Kolom ini menggantikan subscriptionId dari versi sebelumnya.

Kolom SubscriptionPurchaseV2 untuk langganan berulang

purchases.subscriptionv2 berisi kolom baru yang memberikan detail selengkapnya tentang objek langganan baru. Tabel berikut menunjukkan cara kolom dari endpoint langganan lama dipetakan ke kolom yang sesuai dalam purchases.subscriptionv2.

SubscriptionPurchase	SubscriptionPurchaseV2
countryCode	regionCode
orderId	latestOrderId
(tidak ada kolom yang setara)	lineItems (daftar SubscriptionPurchaseLineItem) yang mewakili produk yang diperoleh dengan pembelian
(tidak ada kolom yang setara)	lineItems.offerDetails.basePlanId
(tidak ada kolom yang setara)	lineItems.offerDetails.offerId
(tidak ada kolom yang setara)	lineItems.offerDetails.offerTags
startTimeMillis	startTime
expiryTimeMillis	lineItems.expiryTime (setiap langganan yang diperoleh dalam pembelian memiliki expiryTime-nya sendiri)
(tidak ada kolom yang setara)	subscriptionState (menunjukkan status langganan)
(tidak ada kolom yang setara)	pausedStateContext (hanya ada jika status langganan adalah SUBSCRIPTION_STATE_PAUSED)
autoResumeTimeMillis	pausedStateContext.autoResumeTime
(tidak ada kolom yang setara)	canceledStateContext (hanya ada jika status langganan adalah SUBSCRIPTION_STATE_CANCELED)
(tidak ada kolom yang setara)	testPurchase (hanya ada dalam pembelian penguji berlisensi)
autoRenewing	lineItems.autoRenewingPlan.autoRenewEnabled
priceCurrenceCode, priceAmountMicros, introductoryPriceInfo	(tidak ada kolom yang setara) Informasi ini dapat ditemukan di basePlan/offer untuk setiap langganan yang dibeli.
developerPayload	(tidak ada kolom yang setara) payload developer tidak digunakan lagi
paymentState	(tidak ada kolom yang setara) Anda dapat menyimpulkan status pembayaran dari subscriptionState: Pembayaran tertunda: SUBSCRIPTION_STATE_PENDING (pembelian baru dengan transaksi tertunda) SUBSCRIPTION_STATE_IN_GRACE_PERIOD SUBSCRIPTION_STATE_ON_HOLD Pembayaran telah diterima: SUBSCRIPTION_STATE_ACTIVE Uji coba gratis: (tidak ada kolom yang setara) Upgrade/downgrade yang ditangguhkan: SUBSCRIPTION_STATE_PENDING
cancelReason, userCancellationTimeMillis, cancelSurveyResult	canceledStateContext
linkedPurchaseToken	linkedPurchaseToken (tidak ada perubahan)
purchaseType	Pengujian: melalui testPurchase Promosi: signupPromotion
priceChange	lineItems.autoRenewingPlan.priceChangeDetails
profileName, emailAddress, givenName, familyName, profileId	subscribeWithGoogleInfo
acknowledgementState	acknowledgementState (no change)
promotionType, promotionCode	signupPromotion
externalAccountId, obfuscatedExternalAccountId, obfuscatedExteranlProfileId	externalAccountIdentifiers

Fungsi pengelolaan langganan lainnya

Saat purchases.subscriptions:get telah diupgrade ke purchases.subscriptionsv2:get, fungsi pengelolaan langganan developer lainnya tetap tidak berubah untuk saat ini di endpoint purchases.subscriptions, sehingga Anda dapat terus menggunakan purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund, dan purchases.subscriptions:revoke seperti yang Anda lakukan sebelumnya.

Pricing API

Gunakan endpoint monetization.convertRegionPrices untuk menghitung harga regional seperti yang Anda lakukan melalui Konsol Play. Metode ini menerima satu harga dalam mata uang apa pun yang didukung Play dan menampilkan harga yang dikonversi (termasuk tarif pajak default jika berlaku) untuk semua wilayah tempat Google Play mendukung pembelian.