Panduan ini menjelaskan cara menggunakan Google Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Play.
Untuk menjual produk di aplikasi Anda melalui sistem penagihan Google Play, Anda harus menyiapkan katalog yang berisi semua produk yang ingin disediakan untuk dibeli oleh pengguna. Hal ini dapat dilakukan melalui Konsol Play, atau Anda dapat mengotomatiskan pengelolaan katalog menggunakan Google Play Developer API. Otomatisasi dapat membantu memastikan katalog Anda selalu diperbarui, dan diskalakan ke katalog besar yang tidak dapat dilakukan koordinasi manual. Dalam panduan ini, Anda akan melihat cara menggunakan Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Play. Tinjau panduan Penyiapan untuk mengetahui petunjuk cara menyiapkan Google Play Developer API untuk integrasi backend Anda.
Katalog Management API
Untuk membaca berbagai jenis produk yang dapat Anda jual dengan sistem penagihan Google Play, baca Memahami jenis produk dalam aplikasi dan pertimbangan katalog. Google menawarkan dua set API utama untuk pengelolaan katalog di Play, sesuai dengan dua kategori produk utama:
- Produk sekali beli
- Produk langganan
Produk sekali beli
Endpoint inappproducts
memungkinkan Anda mengelola produk
sekali pakai dari backend. Hal ini termasuk membuat, memperbarui, dan menghapus produk, serta mengelola harga dan ketersediaan.
Bergantung pada cara Anda menangani pembelian produk sekali beli, Anda akan membuat model
produk habis pakai (dapat dibeli sebanyak yang diinginkan) atau hak
permanen (tidak dapat dilakukan dua kali oleh pengguna yang sama). Anda dapat memutuskan produk sekali beli mana yang harus habis pakai atau tidak.
Produk langganan
Endpoint monetization.subscriptions
membantu Anda mengelola produk
langganan dari backend developer Anda. Anda dapat melakukan hal-hal seperti membuat, memperbarui, dan menghapus langganan, atau mengontrol ketersediaan dan harga regional.
Selain endpoint monetization.subscriptions
, kami juga menyediakan
monetization.subscriptions.basePlans
dan
monetization.subscriptions.basePlans.offers
untuk mengelola
paket dasar dan penawaran langganan masing-masing.
Metode batch
Endpoint inappproducts
dan monetization.subscriptions
menyediakan sejumlah metode batch yang memungkinkan pengambilan atau pengelolaan
hingga 100 entity dalam aplikasi yang sama secara bersamaan.
Metode batch, jika digunakan dengan toleransi latensi diaktifkan, mendukung throughput yang lebih tinggi dan sangat berguna bagi developer katalog besar untuk pembuatan katalog awal atau rekonsiliasi katalog.
Memperbarui latensi propagasi versus throughput
Setelah permintaan pembuatan atau modifikasi produk selesai, perubahan mungkin tidak
langsung terlihat oleh pengguna akhir di perangkat mereka karena adanya penundaan pemrosesan jaringan atau
backend.
Secara default, semua permintaan modifikasi produk bersifat sensitif terhadap latensi. Artinya,
dioptimalkan untuk propagasi cepat melalui sistem backend, yang biasanya
merefleksikan perangkat pengguna akhir dalam hitungan menit. Namun, ada batas per jam untuk jumlah permintaan modifikasi tersebut.
Jika Anda perlu membuat atau memperbarui banyak produk (misalnya, selama
pembuatan awal katalog besar), Anda dapat menggunakan metode batch dengan
kolom latencyTolerance
yang ditetapkan ke
PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
.
Tindakan ini akan meningkatkan throughput update secara signifikan. Update yang menoleransi latensi
akan memerlukan waktu hingga 24 jam untuk diterapkan ke perangkat pengguna akhir.
Konfigurasi kuota
Ada beberapa batas kuota yang harus Anda perhatikan saat menggunakan Play Developer API untuk mengelola katalog produk:
- Google Play Developer API memiliki batas default 200.000 kueri per hari. Batas kuota ini berlaku untuk agregasi penggunaan di semua endpoint, termasuk API pengelolaan katalog.
- Endpoint perubahan produk juga menerapkan batas 7.200 kueri per jam. Ini adalah batasan tunggal untuk produk sekali beli dan langganan dan di semua permintaan modifikasi, termasuk pembuatan, update, pengaktifan, penghapusan. Panggilan metode modifikasi batch dihitung sebagai satu kueri untuk kuota ini, terlepas dari jumlah permintaan individual yang disertakan atau sensitivitas latensinya.
- Modifikasi yang sensitif terhadap latensi juga memiliki batas 7.200 modifikasi per jam. Untuk metode batch, setiap permintaan modifikasi bertingkat dihitung secara terpisah untuk tujuan kuota ini. Kuota ini memiliki implikasi praktis hanya untuk pengguna batch API yang melakukan update yang sensitif terhadap latensi, seperti dalam kasus lainnya, kuota 2 akan habis sebelum atau bersamaan dengan kuota ini.
Berikut beberapa contoh ilustratif untuk memahami penggunaan kuota dari berbagai permintaan:
- Satu permintaan
get
untuk mengambil satu item akan menggunakan 1 token kuota 1 dan tanpa token kuota 2 dan 3 (karena hanya terkait dengan endpoint modifikasi). - Permintaan batch
get
untuk mengambil hingga 100 item juga akan menggunakan 1 token kuota 1 dan tidak ada token kuota 2 dan 3. - Satu permintaan
modification
untuk satu item akan menggunakan 1 token dari kuota 1, 1 token kuota 2. Jika permintaan tersebut sensitif terhadap latensi, permintaan juga akan memakai 1 token kuota 3. Karena kuota C memiliki batas yang sama dengan kuota 2, kuota tersebut tidak memiliki implikasi praktis bagi pengguna yang hanya menggunakan metode modifikasi tunggal. - Permintaan batch
modification
untuk 100 item yang toleran latensi akan menggunakan 1 token kuota 1, 1 token kuota 2. Penyiapan kuota ini akan memberikan cukup margin untuk terus memperbarui katalog, tetapi jika algoritme Anda tidak mengetahui kuota ini dan melampaui kapasitas ini, Anda mungkin akan menerima error per panggilan tambahan. - Permintaan batch
modification
untuk 100 item sensitif latensi akan menggunakan 1 token dari kuota 1, 1 token kuota 2, dan 100 token kuota 3.
Rekomendasi penggunaan Catalog Management API
Dengan mematuhi panduan ini, Anda mengoptimalkan interaksi dengan API, memastikan pengalaman pengelolaan katalog yang lancar dan efisien.
Memantau penggunaan Anda
Anda harus mengetahui proses penggunaan yang berat. Misalnya, pada awal integrasi, endpoint pengelolaan katalog Anda kemungkinan besar akan menghabiskan lebih banyak kuota untuk membuat katalog awal yang lengkap, dan hal ini berpotensi memengaruhi penggunaan produksi endpoint lain seperti API status pembelian jika Anda mendekati batas penggunaan keseluruhan. Anda harus memantau pemakaian kuota untuk memastikan Anda tidak melebihi kuota API. Ada beberapa cara untuk memantau penggunaan. Misalnya, Anda dapat menggunakan dasbor kuota Google Cloud API, atau alat pemantauan API internal atau pihak ketiga pilihan Anda.
Mengoptimalkan penggunaan kuota API
Mengoptimalkan pemakaian kapasitas sangat direkomendasikan untuk meminimalkan kemungkinan error API. Untuk menerapkannya secara efektif, sebaiknya Anda:
- Pilih strategi pengelolaan katalog yang tepat. Setelah memahami kuota API, Anda harus memilih strategi yang tepat bagi aplikasi Anda untuk mencapai sasaran pengelolaan katalog secara efisien.
- Hanya lakukan panggilan telepon sesedikit mungkin untuk mencerminkan perubahan Anda.
- Jangan mengirim panggilan modifikasi yang berlebihan atau tidak perlu ke API. Anda mungkin harus menyimpan log perubahan di katalog backend.
- Mematuhi batas perubahan produk per jam sebanyak 7.200 kueri. Anda mungkin ingin mem-build proses sinkronisasi yang mengharuskan Anda melakukan banyak modifikasi produk dalam waktu singkat (misalnya, pembuatan katalog awal). Jika Anda memperkirakan proses ini akan melampaui batas per jam, terapkan waktu tunggu sesuai kebutuhan untuk memperlambat penggunaan ke tingkat aman. Pertimbangkan untuk menggunakan metode batch dengan update yang toleran terhadap latensi untuk mencapai throughput yang lebih tinggi.
- Mempersiapkan secara proaktif untuk menyesuaikan skala. Seiring berkembangnya aplikasi, Anda mungkin perlu meningkatkan penggunaan API dan berbagai endpoint. Baca dokumentasi kuota Google Play Developer API untuk mengetahui detail tentang cara meningkatkan kuota saat Anda hampir mencapai penggunaan maksimum.
- Jadwalkan proses-proses yang berat secara strategis. Cobalah untuk menjadwalkan proses katalog Anda yang berat di seputar puncak penggunaan penting, misalnya, Anda dapat menghindari menjalankan sinkronisasi katalog lengkap selama puncak waktu penjualan dalam seminggu.
Menambahkan logika penanganan error kuota
Tidak peduli seberapa efisien Anda membangun logika pengelolaan katalog, Anda harus
membuat logika tersebut tahan terhadap batas kuota yang tidak terduga, mengingat kuota harian
digunakan bersama oleh endpoint yang digunakan dalam modul independen integrasi Anda. Pastikan Anda menyertakan error throttling kuota dalam penanganan error Anda, dan terapkan waktu tunggu yang sesuai.
Setiap panggilan yang dilakukan ke Google Play Developer API akan menghasilkan respons. Jika terjadi kegagalan panggilan, Anda akan menerima respons kegagalan yang mencakup
kode status respons HTTP dan objek errors
, yang memberikan detail lebih lanjut
tentang domain error dan pesan debug.
Misalnya, jika melampaui batas harian, Anda mungkin akan mengalami error
yang serupa dengan berikut:
{
"code" : 403,
"errors" : [ {
"domain" : "usageLimits",
"message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
"reason" : "dailyLimitExceeded",
"extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
} ],
}
Penerapan pengelolaan katalog
Developer menggunakan endpoint publikasi produk Google Play Developer API untuk menjaga katalog mereka tetap sinkron antara backend dan Google Play. Memastikan katalog Google Play selalu diperbarui dengan informasi terbaru katalog backend memiliki keuntungan untuk menciptakan pengalaman pengguna yang lebih baik. Contoh:
- Anda dapat melihat seluruh daftar penawaran yang tersedia, serta mengelola tag penawaran dan paket dasar untuk memengaruhi logika penayangan penawaran dan kelayakan Anda sendiri.
- Anda dapat memeriksa berbagai titik harga dan detail produk yang dilihat pengguna di berbagai platform, dan memastikannya konsisten.
- Anda akan memiliki detail produk di backend saat memproses pembelian baru, tanpa perlu meningkatkan latensi dan risiko kegagalan dengan melakukan panggilan tambahan ke Google Play Developer API selama alur penting pengguna.
Ada batasan dan pertimbangan tertentu yang harus Anda perhatikan saat membuat katalog produk di Google Play. Setelah memahami batasan ini dan mengetahui cara menyusun katalog, sekarang saatnya memutuskan strategi sinkronisasi Anda.
Strategi sinkronisasi katalog
Endpoint publikasi Google Play Developer API memungkinkan Anda membuat pembaruan pada katalog saat terjadi perubahan. Terkadang, Anda mungkin perlu melakukan pendekatan update berkala, dengan mengirimkan sejumlah perubahan dalam proses yang sama. Setiap pendekatan memerlukan pilihan desain yang berbeda. Setiap strategi sinkronisasi akan cocok dengan beberapa kasus penggunaan lebih baik daripada yang lain, dan Anda mungkin memiliki serangkaian kebutuhan yang memanggil keduanya, bergantung pada situasinya. Terkadang, Anda mungkin ingin melakukan pembaruan produk saat mengetahui perubahan baru, misalnya untuk memproses pembaruan produk yang mendesak (yaitu, harga yang salah harus diperbaiki secepatnya). Pada lain waktu, Anda dapat menggunakan sinkronisasi latar belakang berkala untuk memastikan backend dan katalog Play Anda selalu konsisten. Baca beberapa kasus penggunaan umum saat Anda mungkin ingin menerapkan berbagai strategi pengelolaan katalog ini.
Kapan harus mengirim pembaruan saat katalog lokal Anda berubah
Idealnya, pembaruan harus dilakukan segera setelah ada perubahan pada katalog produk backend Anda, untuk meminimalkan perbedaan.
Jenis update ini adalah opsi yang baik saat:
- Anda harus memastikan bahwa produk Anda selalu diperbarui.
- Anda harus membuat beberapa perubahan pada produk setiap hari.
- Anda perlu memperbarui produk yang sudah diproduksi dan dijual.
Pendekatan ini lebih mudah diterapkan, dan memungkinkan Anda menjaga katalog tetap sinkron dengan periode perbedaan jumlah terkecil.
Kapan harus menggunakan update berkala
Update berkala dijalankan secara asinkron ke edisi produk di backend, dan merupakan opsi yang bagus jika:
- Anda tidak perlu memastikan produk Anda diperbarui dalam waktu singkat.
- Anda perlu merencanakan update massal atau proses konsiliasi.
- Anda sudah memiliki Sistem Pengelolaan Konten atau Katalog untuk menangani produk digital, yang akan terus memperbarui katalog
Untuk katalog besar, sebaiknya gunakan metode batch dengan update yang toleran terhadap latensi untuk mencapai throughput maksimum.
Membuat katalog produk
Jika memiliki katalog besar untuk diupload ke Google Play, Anda mungkin ingin mengotomatiskan pemuatan awal. Jenis proses berat ini akan berfungsi optimal jika strategi berkala yang dikombinasikan dengan metode batch yang toleran terhadap latensi diikuti.
Membuat produk sekali beli
Untuk pembuatan katalog besar produk sekali beli awal, sebaiknya gunakan
metode inappproducts.batchUpdate
dengan kolom allowMissing
ditetapkan ke
true
dan kolom latencyTolerance
ditetapkan ke
PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
.
Tindakan ini akan meminimalkan waktu yang diperlukan untuk membuat katalog sesuai batas kuota.
Untuk katalog yang lebih kecil, Anda dapat menggunakan metode inapp_products.insert
.
Atau, Anda dapat menggunakan metode inappproducts.update
dengan parameter allowMissing
seperti yang dijelaskan di bagian Update produk.
Pendekatan ini bermanfaat meniadakan kebutuhan akan skrip menjadi
stateful dan dapat dimulai ulang dari awal jika terjadi kesalahan.
Membuat produk langganan
Untuk pembuatan katalog besar pada langganan awal, sebaiknya gunakan
metode monetization.subscriptions.batchUpdate
dengan kolom allowMissing
ditetapkan ke true
dan kolom latencyTolerance
ditetapkan
ke PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
.
Tindakan ini akan meminimalkan waktu yang diperlukan untuk membuat katalog sesuai batas kuota.
Untuk katalog langganan yang lebih kecil, Play Developer API menyediakan
metode monetization.subscriptions.create
.
Atau, Anda dapat membuat langganan menggunakan
metode monetization.subscriptions.update
dengan
parameter allowMissing
seperti yang dijelaskan di bagian Update produk.
Semua metode sebelumnya akan membuat langganan beserta paket dasarnya
(disediakan dalam objek Subscription). Paket dasar ini awalnya
tidak aktif. Untuk mengelola status paket dasar, Anda dapat menggunakan endpoint
monetization.subscriptions.basePlans
, termasuk mengaktifkan
paket dasar agar tersedia untuk dibeli.
Selain itu, endpoint monetization.subscriptions.basePlans.offers
memungkinkan Anda membuat dan mengelola penawaran.
Notifikasi produk terbaru
Metode berikut memungkinkan Anda memodifikasi produk yang sudah ada secara efisien, memastikan penawaran Anda selaras dengan penyesuaian terbaru Anda.
Memperbarui produk sekali beli
Ada tiga metode yang tersedia untuk membantu Anda memperbarui produk sekali beli yang sudah ada.
inappproducts.patch
: Endpoint patch digunakan untuk mengupdate resource sebagian. Ini berarti Anda dapat memperbarui kolom tertentu yang Anda tentukan dalam isi permintaan. Endpoint patch biasanya digunakan ketika Anda hanya perlu mengupdate beberapa kolom resource.inappproducts.update
: Endpoint update digunakan untuk mengupdate resource secara keseluruhan. Artinya, Anda harus mengirim seluruh objek resource dalam isi permintaan. Endpoint update biasanya digunakan saat Anda perlu mengupdate semua kolom di resource. Jika parameterallowMissing
ditetapkan ketrue
dan ID produk yang diberikan belum ada, endpoint akan menyisipkan produk, bukan gagal.inappproducts.batchUpdate
: Ini adalah versi batch endpoint update, yang memungkinkan Anda mengubah beberapa produk dengan satu kueri. Gunakan bersama dengan kolomlatencyTolerance
yang ditetapkan kePRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
untuk mencapai throughput yang lebih tinggi.
Memperbarui produk langganan
Untuk memperbarui langganan yang sudah ada, Anda dapat menggunakan
metode monetization.subscriptions.patch
. Metode ini
mengambil parameter yang diperlukan berikut:
packageName
: Nama paket aplikasi yang memiliki langganan.productId
: ID produk unik langganan.regionsVersion
: Versi konfigurasi region.
Kecuali jika Anda membuat langganan baru menggunakan parameter allowMissing
,
Anda harus memberikan parameter updateMask
. Parameter ini adalah
daftar kolom yang dipisahkan koma yang ingin Anda perbarui.
Misalnya, jika Anda hanya ingin memperbarui listingan produk langganan,
Anda harus menentukan kolom listings
ke parameter updateMask
.
Anda dapat menggunakan monetization.subscriptions.batchUpdate
untuk memperbarui beberapa langganan sekaligus.
Gunakan bersama dengan kolom latencyTolerance
yang ditetapkan ke
PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
untuk mencapai throughput
yang lebih tinggi.
Untuk mengaktifkan, menonaktifkan, menghapus paket dasar, atau memigrasikan pelanggan ke
versi harga paket dasar terbaru, gunakan endpoint monetization.subscriptions.basePlans
.
Selain itu, Anda dapat memperbarui penawaran paket dasar dengan metode monetization.subscriptions.basePlans.offers.patch
.
Rekonsiliasi katalog
Baik Anda memilih untuk memperbarui katalog Google Play setiap kali katalog backend Anda berubah atau secara berkala, jika Anda memiliki sistem pengelolaan katalog atau database di luar katalog Google Play, mungkin ada situasi saat katalog tersebut tidak sinkron dengan katalog pada konfigurasi aplikasi Anda di Play. Hal ini dapat disebabkan oleh perubahan katalog manual darurat di Konsol, gangguan pada sistem pengelolaan katalog Anda, atau mungkin jika Anda kehilangan data terbaru.
Anda dapat membuat proses rekonsiliasi katalog untuk menghindari periode perbedaan yang berkepanjangan.
Pertimbangan sistem perbedaan
Sebaiknya, bangun sistem perbedaan untuk mendeteksi inkonsistensi dan merekonsiliasi kedua sistem tersebut. Berikut adalah beberapa hal yang perlu dipertimbangkan saat membuat sistem perbedaan untuk membantu menjaga katalog Anda tetap sinkron:
- Memahami model data: Langkah pertama adalah memahami model data CMS developer dan Google Play Developer API. Hal ini termasuk mengetahui berbagai jenis data yang disimpan di setiap sistem, dan bagaimana elemen data yang berbeda dipetakan satu sama lain.
- Tentukan aturan perbedaan: Setelah memahami model data, Anda perlu menentukan aturan perbedaan. Aturan ini akan menentukan bagaimana data dalam kedua sistem dibandingkan. Misalnya, Anda dapat mencocokkan ID produk dan membandingkan atribut utama langganan serta paket dasar dan penawaran terkait.
- Implementasikan algoritma perbedaan: Setelah menentukan aturan perbedaan, Anda
harus menerapkan algoritma perbedaan. Algoritma ini akan mengambil data dari kedua sistem dan membandingkannya sesuai dengan aturan yang telah Anda tetapkan. Untuk mendapatkan
data katalog dari Google Play, Anda dapat menggunakan metode
inappproducts.list
,inappproducts.batchGet
,monetization.subscriptions.list
danmonetization.subscriptions.batchGet
. - Buat laporan perbedaan: Algoritme perbedaan akan menghasilkan laporan perbedaan. Laporan ini akan menunjukkan perbedaan antara kedua sistem.
- Rekonsiliasi perbedaan: Setelah membuat laporan perbedaan, Anda harus mengatasi perbedaan tersebut. Hal ini mungkin melibatkan pembaruan data di CMS Anda, atau mungkin melibatkan pembaruan data di sisi Google Play menggunakan endpoint pengelolaan katalog Developer API, bergantung pada cara Anda biasanya memperbarui katalog. Untuk merekonsiliasi produk yang tidak sinkron, gunakan endpoint update seperti yang dijelaskan di bagian Update produk.
Penghentian produk
Google Play Developer API menawarkan beberapa metode untuk membantu developer dalam
menghentikan produk mereka:
inappproducts.delete
dan
inappproducts.batchDelete
untuk produk sekali beli dan
monetization.subscriptions.delete
untuk langganan. Penghentian penggunaan produk mungkin diperlukan dalam berbagai skenario, seperti:
- Tidak sengaja dibuat.
- Menghentikan fitur atau layanan.
Sebaiknya gabungkan penghentian penggunaan produk ke dalam strategi pengelolaan katalog Anda.
Menghentikan penggunaan produk sekali beli
Untuk menghapus produk sekali beli dengan Google Play Developer API, Anda harus menggunakan
metode
inappproducts.delete
atau
inappproducts.batchDelete
.
Menghentikan penggunaan produk langganan
Anda dapat menghapus langganan menggunakan
metode
monetization.subscriptions.delete
. Langganan tidak dapat dihapus setelah setidaknya satu paket dasar
diaktifkan.