Panduan ini menjelaskan cara menggunakan Google Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Google Play Anda.
Untuk menjual produk di aplikasi Anda melalui sistem penagihan Google Play, Anda harus menyiapkan katalog yang berisi semua produk yang ingin Anda sediakan 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 terbaru, dan menskalakan ke katalog besar yang tidak praktis untuk dikoordinasikan secara manual. Dalam panduan ini, Anda akan melihat cara menggunakan Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Play Anda. Tinjau panduan Bersiap untuk mendapatkan petunjuk tentang cara menyiapkan Google Play Developer API untuk integrasi backend Anda.
Catalog 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, yang sesuai dengan dua kategori produk utama:
- Produk sekali beli
- Produk langganan
Produk sekali beli
Produk sekali beli (sebelumnya disebut produk dalam aplikasi) menggunakan model objek produk sekali beli yang memungkinkan Anda mengonfigurasi beberapa penawaran dan opsi pembelian untuk produk sekali beli. Model objek produk sekali beli memberi Anda fleksibilitas yang lebih besar dalam cara menjual produk, dan mengurangi kompleksitas pengelolaannya. Produk dalam aplikasi yang ada akan dimigrasikan ke model objek produk sekali beli. Untuk mengetahui informasi selengkapnya, lihat Migrasi produk dalam aplikasi.
Endpoint monetization.onetimeproducts dan
inappproducts memungkinkan Anda
mengelola produk sekali beli dari backend. Hal ini mencakup pembuatan, pembaruan,
dan penghapusan produk, serta pengelolaan 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 dibuat 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 dapat melakukan berbagai hal seperti membuat, memperbarui,
dan menghapus langganan, atau mengontrol ketersediaan dan harga regionalnya. Selain endpoint monetization.subscriptions, kami juga menyediakan monetization.subscriptions.basePlans dan monetization.subscriptions.basePlans.offers untuk mengelola paket dasar dan penawaran langganan.
Metode batch
Endpoint onetimeproducts,
inappproducts, dan monetization.subscriptions
menyediakan sejumlah metode batch yang memungkinkan pengambilan atau pengelolaan hingga
100 entitas di aplikasi yang sama secara bersamaan.
Metode batch, jika digunakan dengan toleransi latensi yang diaktifkan, mendukung throughput yang lebih tinggi dan sangat berguna bagi developer katalog besar untuk pembuatan katalog awal atau rekonsiliasi katalog.
Memperbarui latensi penerapan versus throughput
Setelah permintaan pembuatan atau modifikasi produk selesai, perubahan mungkin tidak
langsung terlihat oleh pengguna akhir di perangkat mereka karena penundaan pemrosesan
jaringan atau backend. Secara default, semua permintaan modifikasi produk
sensitif terhadap latensi. Artinya, parameter ini dioptimalkan untuk penyebaran cepat melalui sistem backend, yang biasanya terlihat di perangkat pengguna akhir dalam hitungan menit.
Namun, ada batas per jam untuk jumlah permintaan modifikasi tersebut.
Untuk kasus saat Anda perlu membuat atau memperbarui banyak produk (misalnya, selama
pembuatan katalog besar awal), 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 toleran terhadap latensi akan memerlukan waktu hingga 24 jam untuk diterapkan ke perangkat pengguna akhir.
Konfigurasi kuota
Ada beberapa batas kuota yang harus Anda ketahui saat menggunakan Play Developer API untuk mengelola katalog produk:
- Google Play Developer API diatur ke dalam kategori yang disebut bucket. Setiap bucket memiliki batas penggunaan per menitnya sendiri. Untuk mengetahui informasi selengkapnya, lihat kuota.
- Endpoint modifikasi produk juga menerapkan batas 7.200 kueri per jam. Ini adalah batas tunggal untuk produk sekali beli dan langganan, serta untuk semua permintaan modifikasi, termasuk pembuatan, update, aktivasi, 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 hanya memiliki implikasi praktis bagi pengguna API batch yang melakukan update yang sensitif terhadap latensi, karena dalam kasus lain, kuota 2 akan habis sebelum atau bersamaan dengan kuota ini.
Berikut beberapa contoh ilustrasi untuk memahami penggunaan kuota dari berbagai permintaan:
- Satu permintaan
getuntuk mengambil satu item akan menggunakan 1 token kuota 1 dan tidak ada token kuota 2 dan 3 (karena hanya terkait dengan endpoint modifikasi). - Permintaan
getbatch untuk mengambil hingga 100 item juga akan menggunakan 1 token kuota 1 dan tidak ada token kuota 2 dan 3. - Satu permintaan
modificationuntuk satu item akan menggunakan 1 token kuota 1, 1 token kuota 2. Jika permintaan sensitif terhadap latensi, permintaan tersebut juga akan menggunakan 1 token dari kuota 3. Karena kuota C memiliki batas yang sama dengan kuota 2, kuota ini tidak memiliki implikasi praktis bagi pengguna yang hanya menggunakan metode modifikasi tunggal. - Permintaan
modificationbatch untuk 100 item yang toleran terhadap latensi akan menggunakan 1 token kuota 1, 1 token kuota 2. Penyiapan kuota ini akan memberikan margin yang cukup untuk terus memperbarui katalog Anda, tetapi jika algoritma Anda tidak menyadari kuota ini dan melampaui batas ini, Anda mungkin akan mendapatkan error per panggilan tambahan. - Permintaan
modificationbatch untuk 100 item yang sensitif terhadap latensi akan menggunakan 1 token kuota 1, 1 token kuota 2, dan 100 token kuota 3.
Rekomendasi penggunaan Catalog Management API
Dengan mematuhi pedoman ini, Anda akan mengoptimalkan interaksi dengan API, sehingga memastikan pengalaman pengelolaan katalog yang lancar dan efisien.
Memantau penggunaan
Anda harus mengetahui proses penggunaan yang berat. Misalnya, pada awal integrasi, endpoint pengelolaan katalog Anda cenderung menggunakan lebih banyak kuota untuk membuat katalog awal lengkap dan hal ini berpotensi memengaruhi penggunaan produksi endpoint lain seperti API status pembelian jika Anda mendekati batas penggunaan keseluruhan. Anda perlu memantau penggunaan kuota untuk memastikan bahwa 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 lainnya pilihan Anda.
Mengoptimalkan penggunaan kuota API
Mengoptimalkan konsumsi kapasitas sangat direkomendasikan untuk meminimalkan kemungkinan error API. Untuk menerapkan hal ini secara efektif, sebaiknya Anda:
- Pilih strategi pengelolaan katalog yang tepat. Setelah memahami kuota API, Anda harus memilih strategi yang tepat untuk aplikasi Anda guna mencapai sasaran pengelolaan katalog secara efisien.
- Hanya lakukan panggilan minimum yang diperlukan untuk mencerminkan perubahan Anda.
- Jangan mengirim panggilan modifikasi yang redundan atau tidak diperlukan ke API. Hal ini mungkin mengharuskan Anda menyimpan changelog di katalog backend.
- Tidak melebihi batas per jam modifikasi produk sebanyak 7.200 kueri. Anda mungkin ingin membangun 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 seperlunya untuk memperlambat penggunaan ke tingkat yang aman. Pertimbangkan untuk menggunakan metode batch dengan update yang toleran terhadap latensi untuk mencapai throughput yang lebih tinggi.
- Bersiaplah secara proaktif untuk melakukan penskalaan. 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 mendekati penggunaan maksimum.
- Jadwalkan proses berat secara strategis. Coba jadwalkan proses katalog yang berat di sekitar puncak penggunaan penting, misalnya Anda dapat menghindari menjalankan sinkronisasi katalog lengkap selama waktu penjualan puncak dalam seminggu.
Menambahkan logika penanganan error kuota
Tidak peduli seberapa efisien Anda membangun logika pengelolaan katalog, Anda harus
membuatnya 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, dan menerapkan
penungguan yang sesuai. Setiap panggilan yang dilakukan ke Google Play Developer API akan menghasilkan
respons. Jika panggilan gagal, Anda akan menerima respons kegagalan
yang menyertakan kode status respons HTTP dan objek errors, yang memberikan
detail lebih lanjut tentang domain error dan pesan debug. Misalnya, jika Anda melampaui batas harian, Anda mungkin akan mengalami error seperti 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"
} ],
}
Implementasi pengelolaan katalog
Developer menggunakan endpoint publikasi produk Google Play Developer API untuk menjaga katalog mereka tetap sinkron antara backend mereka dan Google Play. Memastikan katalog Google Play Anda selalu diperbarui dengan informasi terbaru katalog backend memiliki keuntungan untuk menciptakan pengalaman pengguna yang lebih baik. Contoh:
- Anda akan dapat melihat seluruh daftar penawaran yang tersedia, serta mengelola tag penawaran dan paket dasar untuk memengaruhi kelayakan dan logika penayangan penawaran Anda sendiri.
- Anda dapat memeriksa berbagai titik harga dan detail produk yang dilihat pengguna di berbagai platform, dan memastikan semuanya 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, saatnya memutuskan strategi sinkronisasi Anda.
Strategi sinkronisasi katalog
Endpoint publikasi Google Play Developer API memungkinkan Anda melakukan update pada katalog saat terjadi perubahan. Terkadang, Anda mungkin perlu melakukan pendekatan update berkala, dengan mengirimkan serangkaian perubahan dalam proses yang sama. Setiap pendekatan memerlukan pilihan desain yang berbeda. Setiap strategi sinkronisasi akan lebih cocok untuk beberapa kasus penggunaan daripada yang lain, dan Anda mungkin memiliki serangkaian kebutuhan yang memerlukan keduanya, bergantung pada situasinya.
Terkadang, Anda mungkin ingin memperbarui produk saat mengetahui adanya perubahan baru, misalnya untuk memproses pembaruan produk yang mendesak (yaitu harga yang salah harus segera diperbaiki). Atau, 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.
Waktu pengiriman info terbaru 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 jika:
- Anda harus memastikan bahwa produk Anda selalu yang terbaru.
- Anda perlu melakukan beberapa perubahan pada produk Anda setiap hari.
- Anda perlu memperbarui produk yang sudah dalam tahap produksi dan sedang dijual.
Pendekatan ini lebih mudah diterapkan, dan memungkinkan Anda menjaga katalog tetap sinkron dengan periode perbedaan yang paling sedikit.
Kapan harus menggunakan update berkala
Pembaruan berkala dijalankan secara asinkron ke edisi produk di backend Anda, dan merupakan opsi yang baik jika:
- Anda tidak perlu memastikan produk Anda diperbarui dalam waktu singkat.
- Anda perlu merencanakan update massal atau proses rekonsiliasi.
- Anda sudah memiliki Sistem Pengelolaan Konten atau Katalog untuk menangani produk digital, dan sistem tersebut terus memperbarui katalog Anda
Jika katalog berukuran besar, pertimbangkan untuk menggunakan metode batch dengan update yang toleran terhadap latensi untuk mencapai throughput maksimum.
Membuat katalog produk
Jika Anda memiliki katalog besar untuk diupload ke Google Play, sebaiknya otomatiskan pemuatan awal. Jenis proses berat ini berfungsi paling baik jika strategi berkala yang dikombinasikan dengan metode batch yang toleran terhadap latensi diikuti.
Membuat produk sekali beli
Untuk pembuatan katalog produk sekali beli di awal, sebaiknya gunakan metode
monetization.onetimeproducts.batchUpdate
atau inapp_products.insert 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 dalam batas kuota.
Membuat produk langganan
Untuk pembuatan katalog besar 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 dalam 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.patch dengan
parameter allowMissing seperti yang dijelaskan di bagian Update produk.
Semua metode sebelumnya membuat langganan beserta paket dasarnya
(disediakan dalam objek Langganan). 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.
Update produk
Metode berikut memungkinkan Anda mengubah produk yang ada secara efisien, sehingga memastikan penawaran Anda sesuai dengan penyesuaian terbaru.
Memperbarui produk sekali beli
Metode berikut tersedia untuk membantu Anda memperbarui produk sekali beli yang ada.
- monetization.onetimeproducts.batchUpdate
inappproducts.patch: Endpoint patch digunakan untuk mengupdate resource sebagian. Artinya, Anda dapat memperbarui kolom tertentu yang Anda tentukan dalam isi permintaan. Endpoint patch biasanya digunakan saat Anda hanya perlu memperbarui 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 dalam resource. Jika parameterallowMissingditetapkan ketruedan 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 kolomlatencyToleranceyang ditetapkan kePRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANTuntuk mencapai throughput yang lebih tinggi.
Memperbarui produk langganan
Untuk memperbarui langganan yang ada, Anda dapat menggunakan
metode monetization.subscriptions.patch. Metode ini
mengambil parameter wajib 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
akan 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 mengupdate katalog Google Play setiap kali katalog backend 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 di konfigurasi aplikasi Anda di Play. Hal ini bisa disebabkan oleh perubahan katalog manual darurat di Konsol, pemadaman layanan pada sistem pengelolaan katalog, atau mungkin jika Anda kehilangan data terbaru.
Anda dapat membuat proses rekonsiliasi katalog untuk menghindari periode perbedaan yang berkepanjangan.
Pertimbangan sistem diff
Sebaiknya bangun sistem diff untuk mendeteksi inkonsistensi dan merekonsiliasi kedua sistem. Berikut beberapa hal yang perlu dipertimbangkan saat membuat sistem diff 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 cara elemen data yang berbeda dipetakan satu sama lain.
- Tentukan aturan diff: Setelah memahami model data, Anda perlu menentukan aturan diff. Aturan ini akan menentukan cara data di kedua sistem dibandingkan. Misalnya, Anda mungkin ingin mencocokkan ID produk dan membandingkan atribut utama langganan serta paket dasar dan penawaran terkaitnya.
- Terapkan algoritma diff: Setelah menentukan aturan diff, Anda
perlu menerapkan algoritma diff. Algoritma ini akan mengambil data dari kedua sistem dan membandingkannya sesuai dengan aturan yang telah Anda tentukan. Untuk
mendapatkan data katalog dari Google Play, Anda dapat menggunakan metode
monetization.onetimeproducts.list,monetization.onetimeproducts.batchGet,inappproducts.list,inappproducts.batchGet,monetization.subscriptions.list, danmonetization.subscriptions.batchGet. - Membuat laporan diff: Algoritma diff akan membuat laporan diff. Laporan ini akan menunjukkan perbedaan antara kedua sistem.
- Rekonsiliasi perbedaan: Setelah membuat laporan perbedaan, Anda harus menyelesaikan 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 Pembaruan produk.
Penghentian penggunaan produk
Google Play Developer API menyediakan metode berikut untuk membantu Anda menghentikan penggunaan produk:
Untuk produk sekali beli:
monetization.onetimeproducts.deletemonetization.onetimeproducts.batchDeleteinappproducts.deleteinappproducts.batchDelete
Untuk produk langganan:
monetization.subscriptions.deleteuntuk langganan. Langganan tidak dapat dihapus setelah setidaknya satu paket dasar diaktifkan.
Penghentian penggunaan produk mungkin diperlukan dalam berbagai skenario, seperti:
- Pembuatan yang tidak disengaja.
- Menghentikan fitur atau layanan.
Sebaiknya sertakan penghentian penggunaan produk ke dalam strategi pengelolaan katalog Anda.