The Android Developer Challenge is back! Submit your idea before December 2.

Referensi AIDL Layanan Penagihan Google Play

Peringatan: AIDL tidak digunakan lagi dan akan dihapus dalam rilis mendatang. Untuk menerapkan fitur Layanan Penagihan Google Play, gunakan library Layanan Penagihan Google Play.

Dokumentasi ini menyajikan informasi referensi teknis terkait penggunaan AIDL Layanan Penagihan Google Play.

Kode Respons Server

Tabel berikut berisi semua kode respons server yang dikirimkan dari Google Play ke aplikasi Anda. Google Play mengirim kode respons secara bersamaan sebagai bilangan bulat yang dipetakan ke kunci RESPONSE_CODE di Bundle respons. Aplikasi Anda harus menangani semua kode respons ini.

Tabel 1. Ringkasan kode respons untuk panggilan AIDL Layanan Penagihan Google Play.

Kode Respons Nilai Deskripsi
BILLING_RESPONSE_RESULT_OK 0 Berhasil
BILLING_RESPONSE_RESULT_USER_CANCELED 1 Pengguna menekan kembali atau membatalkan dialog
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 Sambungan jaringan melemah
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 Versi AIDL Layanan Penagihan Google Play tidak didukung untuk jenis yang diminta
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Produk yang diminta tidak tersedia untuk dibeli
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Argumen yang tidak valid diberikan ke API. Error ini juga dapat menandakan bahwa aplikasi tidak ditandatangani dengan benar atau disiapkan dengan tepat untuk Layanan Penagihan Google Play, atau tidak memiliki izin yang diperlukan dalam manifesnya
BILLING_RESPONSE_RESULT_ERROR 6 Error fatal selama tindakan API
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Kegagalan membeli karena item sudah dimiliki
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Kegagalan mengonsumsi karena item tidak dimiliki

Referensi AIDL Dukungan Layanan Penagihan Google Play

Bagian ini menjelaskan metode untuk memperoleh informasi tentang jenis dukungan Layanan Penagihan Google Play yang tersedia untuk aplikasi Anda.

Metode isBillingSupported()

Metode ini menandakan apakah:

  • Versi API yang diberikan didukung untuk aplikasi Anda.
  • Google Play mendukung penagihan di negara pengguna.
  • Layanan Penagihan Google Play diaktifkan dalam paket aplikasi Anda.
  • Aplikasi Anda dapat menggunakan jenis item yang diberikan untuk tujuan penagihan.

Tabel 2. Paramater isBillingSupported().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 3 dan yang lebih baru.

Metode isBillingSupportedExtraParams()

Metode ini sama persis dengan isBillingSupported(), kecuali bahwa dalam metode ini Anda dapat meneruskan argumen keempat, yaitu Bundle, yang dapat berisi parameter ekstra.

Tabel 3. Parameter isBillingSupportedExtraParams().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.
extraParams Bundle

Kumpulan parameter ekstra yang menentukan lebih lanjut jenis Layanan Penagihan Google Play yang didukung oleh aplikasi.

Paket ini dapat berisi kunci opsional yang disebut vr, yang memiliki nilai boolean. Tanda ini menentukan apakah aplikasi ini mendukung alur pembelian virtual reality (VR).

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 7 dan yang lebih baru.

Referensi AIDL Detail Layanan Penagihan Google Play

AIDL Layanan Penagihan Google Play didefinisikan dalam file IInAppBillingService.aidl, yang disertakan dengan aplikasi contoh Versi 3.

Metode getSkuDetails()

Gunakan metode getSkuDetails() untuk mendapatkan detail produk dari daftar ID produk yang sesuai.

Tabel 4. GetSkuDetails() parameters.

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Jenis item dalam aplikasi ("inapp" untuk pembelian satu kali dan "subs" untuk langganan).
skusBundle Bundle Paket yang berisi StringArrayList SKU dengan kunci ITEM_ID_LIST.

Jika metode getSkuDetails() berhasil, Google Play mengirimkan Bundle respons. . Hasil kueri disimpan di Bundle dalam String ArrayList yang dipetakan ke kunci DETAILS_LIST . Tiap String dalam daftar detail berisi detail produk untuk satu produk dalam format JSON. Kolom dalam string JSON dengan detail produk diringkas dalam tabel 5.

Tabel 5. Deskripsi kolom JSON dengan detail item produk yang dikembalikan dari permintaan getSkuDetails().

Kunci Deskripsi
productId ID produk untuk produk.
type Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.
price Harga format item, termasuk tanda mata uangnya. Harga tidak termasuk pajak.
price_amount_micros Harga dalam unit mikro, dengan 1.000.000 unit mikro setara dengan satu unit mata uang. Misalnya, jika price adalah "€7.99", price_amount_micros adalah "7990000". Nilai ini melambangkan harga yang sudah dilokalkan dan dibulatkan untuk mata uang tertentu.
price_currency_code Kode mata uang ISO 4217 untuk price. Misalnya, jika price ditentukan dalam pounds sterling Inggris, price_currency_code adalah "GBP".
title Judul produk.
description Deskripsi produk.
subscriptionPeriod Periode langganan, ditentukan dalam format ISO 8601. Misalnya, P1W sama dengan satu minggu, P1M sama dengan satu bulan, P3M sama dengan tiga bulan, P6M sama dengan enam bulan, dan P1Y sama dengan satu tahun.

Catatan: Dikembalikan hanya untuk langganan.

freeTrialPeriod Periode uji coba yang dikonfigurasi di Konsol Google Play, yang ditentukan dalam format ISO 8601. Misalnya , P7D sama dengan tujuh hari. Untuk mempelajari lebih lanjut tentang kelayakan uji coba gratis, lihat Langganan dalam aplikasi.

Catatan: Dikembalikan hanya untuk langganan dengan periode uji coba yang telah dikonfigurasi.

introductoryPrice Harga perkenalan format langganan, termasuk tanda mata uang, seperti €3.99. Harga tidak termasuk pajak.

Catatan: Dikembalikan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.

introductoryPriceAmountMicros Harga perkenalan dalam unit mikro. Mata uangnya sama dengan price_currency_code.

Catatan: Dikembalikan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.

introductoryPricePeriod Periode penagihan harga perkenalan, yang ditentukan dalam format ISO 8601.

Catatan: Dikembalikan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.

introductoryPriceCycles Jumlah periode penagihan langganan yang memberikan harga perkenalan kepada pengguna, seperti 3.

Catatan: Dikembalikan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.

Metode getBuyIntent()

Metode ini menampilkan integer kode respons yang dipetakan ke kunci RESPONSE_CODE, dan PendingIntent untuk meluncurkan alur pembelian untuk item dalam aplikasi yang dipetakan ke kunci BUY_INTENT, sebagaimana dijelaskan dalam Menerapkan Layanan Penagihan Google Play. Saat menerima PendingIntent, Google Play mengirim Intent respons beserta data untuk pesanan pembelian tersebut. Data yang ditampilkan dalam Intent respons dirangkum pada tabel 6.

Catatan: Daripada menggunakan metode ini, sebaiknya gunakan getBuyIntentExtraParams(), yang menyediakan fungsi tambahan.

Tabel 6. Data respons dari permintaan pembelian Layanan Penagihan Google Play.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika pembelian berhasil, error jika tidak.
INAPP_PURCHASE_DATA String dalam format JSON yang berisi detail tentang pesanan pembelian. Lihat tabel 7 untuk deskripsi kolom JSON.
INAPP_DATA_SIGNATURE String yang berisi tanda tangan data pembelian yang ditandatangani dengan kunci pribadi developer. Tanda tangan data menggunakan skema RSASSA-PKCS1-v1_5.

Tabel 7 menjelaskan kolom JSON yang dikembalikan dalam data respons untuk pesanan pembelian.

Tabel 7. Deskripsi kolom JSON untuk INAPP_PURCHASE_DATA.

Kolom Deskripsi
autoRenewing Menandakan apakah langganan diperpanjang otomatis. Jika true, langganan aktif, dan akan diperpanjang otomatis pada tanggal penagihan berikutnya. Jika false, menandakan bahwa pengguna telah membatalkan langganan. Pengguna memiliki akses ke konten langganan hingga tanggal penagihan berikutnya dan akan kehilangan akses pada waktu tersebut, kecuali pengguna mengaktifkan kembali perpanjangan otomatis (atau secara manual melakukan perpanjangan, seperti dijelaskan di Perpanjangan Manual). Jika Anda menawarkan masa tenggang, nilai ini tetap ditetapkan ke true untuk semua langganan, selama masa tenggang belum berakhir. Tanggal penagihan berikutnya diperpanjang secara dinamis setiap hari hingga akhir masa tenggang atau hingga pengguna memperbaiki metode pembayarannya.
orderId ID pesanan unik untuk transaksi. ID ini sesuai dengan ID pesanan pembayaran Google.
packageName Paket aplikasi tempat asal pembelian.
productId Kode produk item. Setiap item memiliki ID produk, yang harus Anda tentukan pada daftar produk aplikasi di Konsol Google Play.
purchaseTime Waktu produk dibeli, dalam milidetik sejak waktu acuan (1 Jan 1970).
purchaseState Status pembelian pesanan. Status ini selalu mengembalikan 0 (dibeli).
developerPayload String yang ditentukan oleh developer yang berisi informasi tambahan tentang pesanan. Anda dapat menentukan nilai untuk kolom ini saat melakukan permintaan getBuyIntent.
purchaseToken Token yang secara unik mengidentifikasi pembelian untuk pasangan item dan pengguna tertentu.

Metode consumePurchase()

Mengonsumsi pembelian yang sesuai dengan token pembelian yang diberikan. Metode ini akan menyebabkan dihapusnya item ini dari semua respons berikutnya terhadap getPurchases() dan memungkinkan pembelian kembali item dengan SKU yang sama.

Tabel 8. Parameter consumePurchase().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
purchaseToken String Token dalam JSON informasi pembelian yang mengidentifikasi pembelian yang akan dikonsumsi.

Metode ini mengembalikan RESULT_OK(0) dari konsumsi yang berhasil, dan kode respons yang sesuai jika terjadi kegagalan.

Metode getBuyIntentToReplaceSkus()

Metode ini digunakan untuk mengupgrade atau mendowngrade pembelian langganan. Metode ini mirip dengan getBuyIntent(), kecuali bahwa metode ini mengambil daftar dengan satu SKU yang telah dibeli yang akan diganti dengan SKU yang sedang dibeli. Saat pengguna menyelesaikan pembelian, Google Play menukar SKU lama dan memberikan kredit kepada pengguna dengan nilai waktu langganannya yang tidak terpakai secara prorata. Google Play menerapkan kredit ini ke langganan baru, dan akan mulai menagih pengguna untuk langganan baru setelah kredit habis terpakai.

Catatan: Daripada menggunakan metode ini, sebaiknya gunakan getBuyIntentExtraParams(), yang menyediakan fungsi tambahan.

Metode ini ditambahkan pada AIDL Layanan Penagihan Google Play versi 5. Untuk memverifikasi bahwa metode ini dilaporkan, kirim permintaan AIDL isBillingSupported.

Catatan: Anda hanya dapat menggunakan metode ini untuk pembelian langganan. Jika parameter type yang diteruskan bukan "subs", metode ini akan menampilkan BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Selain itu, SKU yang diteruskan mungkin tidak menyertakan SKU untuk langganan per season.

Metode ini menampilkan integer kode respons yang dipetakan ke kunci RESPONSE_CODE, dan PendingIntent untuk meluncurkan alur pembelian untuk langganan dalam aplikasi yang dipetakan ke kunci BUY_INTENT, sebagaimana dijelaskan dalam Menerapkan Layanan Penagihan Google Play. Saat menerima PendingIntent, Google Play mengirim Intent respons beserta data untuk pesanan pembelian tersebut. Data yang ditampilkan dalam Intent respons dirangkum pada tabel 9.

Tabel 9. Data respons dari permintaan pembelian AIDL Layanan Penagihan Google Play Versi 5.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika pembelian berhasil. Jika pembelian gagal, berisi kode error.
INAPP_PURCHASE_DATA String dalam format JSON yang berisi detail tentang pesanan pembelian. Lihat tabel 6 untuk deskripsi kolom JSON.
INAPP_DATA_SIGNATURE String yang berisi tanda tangan data pembelian yang ditandatangani oleh developer dengan kunci pribadinya. Tanda tangan data menggunakan skema RSASSA-PKCS1-v1_5.

Metode getBuyIntentExtraParams()

Metode ini memulai permintaan pembelian. Metode ini adalah varian dari metode getBuyIntent(), dan mengambil parameter extraParams tambahan. Parameter ini adalah Bundle kunci dan nilai opsional yang memengaruhi operasi metode sebagaimana ditampilkan pada tabel 10.

Tabel 10. Parameter tambahan getBuyIntentExtraParams() .

Kunci Jenis Deskripsi
skusToReplace List<String> Daftar opsional dengan satu SKU yang akan diupgrade atau didowngrade oleh pengguna. Teruskan kolom ini jika pembelian mengupgrade atau mendowngrade langganan yang sudah ada. SKU yang ditentukan diganti dengan SKU yang sedang dibeli oleh pengguna. Google Play menggantikan SKU yang ditentukan di awal siklus penagihan berikutnya.
replaceSkusProration boolean

Menentukan apakah pengguna harus diberikan kredit atas waktu langganan yang tidak terpakai pada SKU yang sedang diupgrade atau didowngrade. Jika Anda menyetel kolom ini ke true, Google Play menukar SKU lama dan memberikan kredit kepada pengguna dengan nilai waktu langganannya yang tidak terpakai secara prorata. Google Play menerapkan kredit ini ke langganan baru, dan akan mulai menagih pengguna untuk langganan baru setelah kredit habis terpakai.

Jika Anda menyetel kolom ini ke false, pengguna tidak menerima kredit untuk waktu langganan yang tidak terpakai, dan tanggal pengulangan tidak berubah.

Nilai default adalah true. Diabaikan jika Anda tidak meneruskan skusToReplace.

accountId String

String obfuscation opsional yang secara unik terkait dengan akun pengguna di aplikasi Anda. Jika Anda meneruskan nilai ini, Google Play dapat menggunakannya untuk mendeteksi aktivitas yang tidak wajar, seperti banyak perangkat melakukan pembelian di akun yang sama dalam waktu singkat.

Kolom ini mirip dengan developerId karena mewakili satu pengguna, tetapi perhatikan bahwa jika Anda memiliki banyak aplikasi, pengguna yang sama dapat memiliki accountId berbeda untuk setiap aplikasi, padahal developerId harus mengidentifikasi secara unik satu pengguna di semua aplikasi Anda.

Jangan gunakan ID developer Konsol Google Play atau ID Google pengguna untuk kolom ini. Selain itu, kolom ini tidak boleh berisi ID pengguna dalam cleartext. Sebaiknya gunakan hash satu arah untuk membuat string dari ID pengguna, dan simpan string yang di-hash di kolom ini.

developerId String

String obfuscation opsional yang secara unik terkait dengan akun pengguna di aplikasi Anda. Kolom ini mirip dengan accountId karena mewakili satu pengguna. Namun, kolom ini harus sama di semua aplikasi Anda untuk pengguna yang sama, sedangkan accountId mungkin unik untuk setiap aplikasi, bahkan untuk pengguna yang sama.

Jangan gunakan ID developer Konsol Google Play atau ID Google pengguna untuk kolom ini. Selain itu, kolom ini tidak boleh berisi ID pengguna dalam cleartext. Sebaiknya gunakan hash satu arah untuk membuat string dari ID pengguna, dan simpan string yang di-hash di kolom ini.

vr boolean

Menentukan apakah intent yang diberikan melambangkan awal alur pembelian virtual reality (VR).

Catatan: Agar parameter tambahan ini berpengaruh pada aplikasi Anda, Anda harus menggunakan AIDL Layanan Penagihan Google Play Versi 7, atau API yang lebih baru.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 6 dan yang lebih baru.

Metode getPurchases()

Metode ini mengembalikan produk yang saat ini tidak dikonsumsi, yang dimiliki oleh pengguna, termasuk item yang dibeli dan item yang diperoleh dengan menukarkan kode promo. Tabel 11 mencantumkan data respons yang ditampilkan di Bundle.

Tabel 11. Data respons dari permintaan getPurchases.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika permintaan berhasil, error jika tidak.
INAPP_PURCHASE_ITEM_LIST StringArrayList yang berisi daftar id produk pembelian dari aplikasi ini.
INAPP_PURCHASE_DATA_LIST StringArrayList yang berisi detail pembelian dari aplikasi ini. Lihat tabel 4 untuk melihat informasi mendetail yang disimpan di setiap item dalam daftar.
INAPP_DATA_SIGNATURE_LIST StringArrayList yang berisi tanda tangan pembelian dari aplikasi ini.
INAPP_CONTINUATION_TOKEN String yang berisi token kelanjutan untuk mengambil kumpulan produk dalam aplikasi berikutnya yang dimiliki oleh pengguna. Ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki oleh pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya mengembalikan pembelian lainnya dan mungkin token kelanjutan lain.

Metode getPurchaseHistory()

Metode ini mengembalikan pembelian terbaru yang dilakukan oleh pengguna untuk tiap SKU, meski pembelian tersebut telah berakhir, dibatalkan, atau dikonsumsi. Tabel 12 mencantumkan data respons yang ditampilkan di Bundle:

Tabel 12. Data respons dari permintaan getPurchaseHistory.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika permintaan berhasil, error jika tidak.
INAPP_PURCHASE_ITEM_LIST StringArrayList yang berisi daftar id produk pembelian dari aplikasi ini.
INAPP_PURCHASE_DATA_LIST StringArrayList yang berisi detail pembelian baru-baru ini dari aplikasi ini. Lihat tabel 6 untuk daftar informasi mendetail yang tersimpan di setiap item INAPP_PURCHASE_DATA dalam daftar.
INAPP_DATA_SIGNATURE_LIST StringArrayList yang berisi tanda tangan pembelian dari aplikasi ini.
INAPP_CONTINUATION_TOKEN String yang berisi token kelanjutan untuk mengambil kumpulan produk dalam aplikasi berikutnya yang dimiliki oleh pengguna. Ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki oleh pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya mengembalikan pembelian lainnya dan mungkin token kelanjutan lain.

Tabel 13. Deskripsi kolom JSON untuk histori pembelian yang dikembalikan oleh getPurchaseHistory().

Kolom Deskripsi
productId Kode produk item. Setiap item memiliki ID produk, yang harus Anda tentukan pada daftar produk aplikasi di Konsol Google Play.
purchaseTime Waktu produk dibeli, dalam milidetik sejak waktu acuan (1 Jan 1970).
developerPayload String yang ditentukan oleh developer yang berisi informasi tambahan tentang pesanan. Anda dapat menentukan nilai untuk kolom ini saat melakukan permintaan getBuyIntent.
purchaseToken Token yang secara unik mengidentifikasi pembelian untuk pasangan item dan pengguna tertentu.

Catatan: Metode getPurchaseHistory() memiliki overhead yang lebih tinggi daripada getPurchases(), karena memerlukan panggilan ke server Google Play. Sebaiknya gunakan getPurchases() jika Anda tidak begitu memerlukan histori pembelian pengguna.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 6 dan yang lebih baru.