Mengelola katalog produk Anda

Panduan ini menjelaskan cara menggunakan Google Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Play Anda.

Untuk menjual produk di aplikasi melalui sistem penagihan Google Play, Anda perlu menyiapkan katalog dengan 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 diperbarui, dan diskalakan ke katalog besar yang koordinasi manualnya tidak praktis. Dalam panduan ini, Anda akan melihat cara menggunakan Play Developer API untuk membuat dan mengelola katalog produk untuk aplikasi Play Anda. Tinjau panduan Bersiap kami untuk mendapatkan petunjuk tentang cara menyiapkan Google Play Developer API untuk integrasi backend Anda.

Catalog Management API

Untuk membaca tentang berbagai jenis produk yang dapat Anda jual dengan sistem penagihan Google Play, baca Memahami jenis produk dalam aplikasi dan pertimbangan katalog. Google menawarkan dua kumpulan API utama untuk pengelolaan katalog di Play, yang sesuai dengan dua kategori produk utama:

  • Produk sekali beli
  • Produk langganan

Produk sekali beli

Endpoint inappproducts memungkinkan Anda mengelola produk satu kali 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 tetap (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 inappproducts dan monetization.subscriptions menyediakan sejumlah metode batch yang memungkinkan pengambilan atau pengelolaan hingga 100 entitas dalam 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 penyebaran versus throughput

Setelah permintaan pembuatan atau perubahan produk selesai, perubahan mungkin tidak langsung terlihat oleh pengguna akhir di perangkat mereka karena penundaan pemrosesan jaringan atau backend. Secara default, semua permintaan perubahan produk sensitif terhadap latensi. Artinya, API ini dioptimalkan untuk penyebaran yang cepat melalui sistem backend, yang biasanya tercermin di perangkat pengguna akhir dalam hitungan menit. Namun, ada batas per jam untuk jumlah permintaan perubahan tersebut. Jika 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. Hal 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:

  1. 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.
  2. Endpoint perubahan produk juga menerapkan batas 7.200 kueri per jam. Batas ini berlaku untuk produk sekali beli dan langganan, serta untuk semua permintaan perubahan, termasuk pembuatan, pembaruan, pengaktifan, dan penghapusan. Panggilan metode perubahan batch dihitung sebagai satu kueri untuk kuota ini, terlepas dari jumlah permintaan individual yang disertakan atau sensitivitas latensi mereka.
  3. Modifikasi sensitif latensi juga memiliki batas 7.200 modifikasi per jam. Untuk metode batch, setiap permintaan perubahan bertingkat dihitung secara terpisah untuk tujuan kuota ini. Kuota ini memiliki implikasi praktek hanya untuk pengguna batch API yang melakukan update sensitif latensi, seperti dalam kasus lain, kuota 2 akan habis sebelum atau pada waktu yang sama dengan kuota ini.

Berikut beberapa contoh ilustrasi untuk memahami penggunaan kuota dari berbagai permintaan:

  • Satu permintaan get untuk mengambil satu item akan menggunakan 1 token kuota 1 dan tidak ada token kuota 2 dan 3 (karena hanya berkaitan dengan endpoint modifikasi).
  • Permintaan get batch 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 kuota 1, 1 token kuota 2. Jika sensitif terhadap latensi, permintaan juga akan menggunakan 1 token kuota 3. Karena kuota C memiliki batas yang sama dengan kuota 2, kuota ini tidak memiliki implikasi praktis bagi pengguna yang hanya menggunakan satu metode perubahan.
  • Permintaan modification batch untuk 100 item yang toleran terhadap latensi akan menggunakan 1 token kuota 1, 1 token kuota 2. Penyiapan kuota ini akan memberikan margin yang memadai untuk terus memperbarui katalog Anda, tetapi jika algoritma Anda tidak memperhatikan kuota ini dan melampaui tarif ini, Anda mungkin akan mendapatkan error per panggilan tambahan.
  • Permintaan modification batch untuk 100 item sensitif latensi akan menggunakan 1 token 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, sehingga memastikan pengalaman pengelolaan katalog yang lancar dan efisien.

Memantau penggunaan

Anda harus mengetahui proses penggunaan yang berat. Misalnya, di 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 sudah mendekati batas penggunaan secara keseluruhan. Anda perlu memantau penggunaan kuota untuk memastikan bahwa Anda tidak melampaui kuota API. Ada beberapa cara untuk memantau penggunaan. Misalnya, Anda dapat menggunakan dasbor kuota Google Cloud API, atau alat pemantauan API pihak ketiga atau internal lainnya sesuai pilihan Anda.

Mengoptimalkan penggunaan kuota API

Mengoptimalkan konsumsi kapasitas sangat direkomendasikan untuk meminimalkan kemungkinan error API. Untuk menerapkannya secara efektif, sebaiknya:

  • Pilih strategi pengelolaan katalog yang tepat. Setelah memahami kuota API, Anda perlu memilih strategi yang tepat untuk aplikasi agar dapat mencapai sasaran pengelolaan katalog secara efisien.
  • Hanya lakukan jumlah panggilan minimum yang diperlukan untuk mencerminkan perubahan Anda.
  • Jangan mengirim panggilan modifikasi yang berlebihan atau tidak perlu ke API. Hal ini mungkin mengharuskan Anda menyimpan log perubahan di katalog backend.
  • Jangan melebihi batas kueri per jam untuk perubahan produk,yaitu 7.200 kueri. Anda mungkin ingin membuat proses sinkronisasi yang mengharuskan Anda melakukan modifikasi produk dalam jumlah besar dalam jangka waktu singkat (misalnya, pembuatan katalog awal). Jika Anda memperkirakan proses ini akan melebihi batas per jam, terapkan penantian sesuai kebutuhan 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 untuk melakukan penskalaan secara proaktif. Seiring berkembangnya aplikasi, Anda mungkin perlu menskalakan 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 berat di sekitar puncak penggunaan yang penting, misalnya Anda dapat menghindari menjalankan sinkronisasi katalog lengkap selama waktu puncak penjualan dalam seminggu.

Menambahkan logika penanganan error kuota

Tidak peduli seberapa efisien Anda membuat logika pengelolaan katalog, Anda harus membuatnya tahan terhadap batas kuota yang tidak terduga, mengingat kuota harian dibagikan oleh endpoint yang digunakan dalam modul independen integrasi Anda. Pastikan Anda menyertakan error throttling kuota dalam penanganan error, dan terapkan penantian yang sesuai. Setiap panggilan yang dilakukan ke Google Play Developer API akan menghasilkan respons. Jika terjadi kegagalan panggilan, 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 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"
  } ],
}

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 Anda selalu diperbarui dengan informasi terbaru katalog backend Anda memiliki keunggulan untuk menciptakan pengalaman pengguna yang lebih baik. Contoh:

  • Anda dapat melihat seluruh daftar penawaran yang tersedia, dan mengelola tag penawaran dan paket dasar untuk memengaruhi logika kelayakan dan penayangan penawaran Anda sendiri.
  • Anda dapat memeriksa berbagai titik harga dan detail produk yang dilihat pengguna di seluruh 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 batas ini dan mengetahui cara Anda ingin menyusun katalog, saatnya menentukan strategi sinkronisasi.

Strategi sinkronisasi katalog

Endpoint publikasi Google Play Developer API memungkinkan Anda melakukan update pada katalog saat perubahan terjadi. Terkadang, Anda mungkin perlu menggunakan pendekatan update berkala, yaitu mengirim serangkaian 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 memerlukan keduanya, bergantung pada situasinya. Terkadang Anda mungkin ingin melakukan pembaruan pada produk saat mengetahui perubahan baru, misalnya untuk memproses pembaruan produk yang mendesak (yaitu harga yang salah harus diperbaiki segera). Terkadang, Anda dapat menggunakan sinkronisasi latar belakang berkala untuk memastikan backend dan katalog Play 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 jika:

  • Anda harus memastikan bahwa produk Anda selalu yang terbaru.
  • Anda perlu melakukan beberapa perubahan pada produk setiap hari.
  • Anda perlu memperbarui produk yang sudah diproduksi dan dijual.

Pendekatan ini lebih mudah diterapkan, dan memungkinkan Anda menyinkronkan katalog dengan periode perbedaan jumlah yang paling sedikit.

Kapan harus menggunakan update berkala

Pembaruan berkala dijalankan secara asinkron dengan edisi produk di backend Anda, dan merupakan opsi yang baik jika:

  • Anda tidak perlu memastikan produk Anda diperbarui dalam waktu singkat.
  • Anda perlu merencanakan pembaruan massal atau proses konsiliasi.
  • 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 memiliki katalog besar untuk diupload ke Google Play, sebaiknya otomatiskan muat awal. Jenis proses berat ini berfungsi paling baik jika strategi berkala digabungkan dengan metode batch yang toleran terhadap latensi diikuti.

Membuat produk sekali beli

Untuk pembuatan katalog besar produk satu kali 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 dalam 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 memiliki manfaat untuk menghilangkan kebutuhan skrip Anda agar bersifat stateful dan dapat dimulai ulang dari awal jika terjadi masalah.

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 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 mengubah produk yang ada secara efisien, sehingga memastikan penawaran Anda selaras dengan penyesuaian terbaru.

Memperbarui produk sekali beli

Ada tiga metode yang tersedia untuk membantu memperbarui produk sekali beli yang ada.

  • inappproducts.patch : Endpoint patch digunakan untuk memperbarui resource sebagian. Artinya, Anda dapat memperbarui kolom tertentu yang Anda tentukan dalam isi permintaan. Endpoint patch biasanya digunakan jika Anda hanya perlu memperbarui beberapa kolom resource.
  • inappproducts.update : Endpoint pembaruan digunakan untuk memperbarui resource secara keseluruhan. Artinya, Anda harus mengirim seluruh objek resource dalam isi permintaan. Endpoint update biasanya digunakan saat Anda perlu memperbarui semua kolom dalam resource. Jika parameter allowMissing ditetapkan ke true dan kode produk yang diberikan belum ada, endpoint akan menyisipkan produk bukan gagal.
  • inappproducts.batchUpdate : Ini adalah versi batch dari endpoint update, yang memungkinkan Anda mengubah beberapa produk dengan satu kueri. Gunakan bersama dengan kolom latencyTolerance yang ditetapkan ke PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT untuk mencapai throughput yang lebih tinggi.

Memperbarui produk langganan

Untuk memperbarui langganan yang ada, Anda dapat menggunakan metode monetization.subscriptions.patch. Metode ini menggunakan parameter wajib berikut:

  • packageName: Nama paket aplikasi yang menjadi milik 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 hanya ingin memperbarui listingan produk langganan, Anda harus menentukan kolom listings ke parameter updateMask.

Anda dapat menggunakan monetization.subscriptions.batchUpdate untuk memperbarui beberapa langganan secara bersamaan. 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 mungkin disebabkan oleh perubahan katalog manual darurat di Konsol, pemadaman 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 buat sistem perbedaan untuk mendeteksi inkonsistensi dan merekonsiliasi dua sistem. Berikut 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 mencakup mengetahui berbagai jenis data yang disimpan di setiap sistem, dan cara berbagai elemen data dipetakan satu sama lain.
  • Menentukan aturan perbedaan: Setelah memahami model data, Anda perlu menentukan aturan perbedaan. Aturan ini akan menentukan cara data di kedua sistem dibandingkan. Misalnya, Anda dapat mencocokkan ID produk dan membandingkan atribut utama langganan serta paket dasar dan penawaran terkait.
  • Terapkan 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 tentukan. Untuk mendapatkan data katalog dari Google Play, Anda dapat menggunakan metode inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list, dan monetization.subscriptions.batchGet.
  • Buat laporan perbedaan: Algoritma perbedaan akan membuat laporan perbedaan. Laporan ini akan menunjukkan perbedaan antara kedua sistem tersebut.
  • Menyatukan 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 Update produk.

Penghentian penggunaan 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:

  • Pembuatan secara tidak sengaja.
  • Menghentikan fitur atau layanan.

Sebaiknya sertakan penghentian produk ke dalam strategi pengelolaan katalog Anda.

Penghentian produk sekali beli

Untuk menghapus produk satu kali 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 minimal satu paket dasar diaktifkan.