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, atauCANCELED. - 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
subscriptionIddari 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 |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
(tidak ada kolom yang setara) Informasi ini dapat ditemukan di 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:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (tidak ada perubahan) |
purchaseType |
Pengujian: melalui testPurchasePromosi: 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.