Menerapkan Layanan Penagihan Play di PWA Anda

Jika PWA Anda tercantum di Google Play dan Anda ingin memonetisasinya dengan menjual produk dalam aplikasi atau langganan, kebijakan Play akan mewajibkan Anda menerapkan Layanan Penagihan Play. Ada dua API yang perlu Anda terapkan di PWA: Digital Goods API dan Payment Request API.

Digital Goods API

Digital Goods API adalah antarmuka antara aplikasi Anda dan Google Play. Dengan begitu, Anda dapat mengambil produk digital dan detail yang telah Anda masukkan untuk produk dalam aplikasi dan langganan di Konsol Play, serta mengambil pembelian yang telah dilakukan pengguna. Jika Anda belum menambahkan produk dalam aplikasi atau langganan di Konsol Play, pastikan untuk mengikuti penyiapan Konsol Play untuk Penagihan Play.

Pada 30 November 2021, ChromeOS 96 dirilis dengan penerapan Digital Goods API 2.0.

Uji coba origin untuk versi pertama Digital Goods API berakhir pada 30 Januari 2022. Oleh karena itu, API ini tidak digunakan lagi dan hanya API v2 yang tersedia.

Pada 23 Juni 2022, ChromeOS 103 dirilis dengan penerapan Digital Goods API 2.1. Rilis ini tidak memiliki perubahan yang dapat menyebabkan gangguan dan hanya mencakup metode baru dan kolom tambahan: listPurchaseHistory() dan itemType.

Mendaftar untuk Uji Coba Origin

Catatan: Digital Goods API saat ini tersedia melalui Uji Coba Origin - mekanisme yang memungkinkan developer mendapatkan akses awal ke Web API baru. Anda harus mendaftar ke uji coba origin Digital Goods API v2 dan meminta token, yang harus Anda berikan di halaman mana pun di origin Anda.

Setelah mendaftar uji coba origin, Anda akan melihat tanggal “Valid Hingga” yang menunjukkan kapan token Anda dijamin berfungsi. Jangan lupa untuk memperpanjang masa berlaku token Anda saat tanggal tersebut mendekat agar dapat terus berpartisipasi dalam uji coba. API yang ditawarkan sebagai uji coba origin dapat berubah, jadi pastikan Anda selalu mendapatkan info terbaru tentang perubahan terbaru pada uji coba origin yang Anda ikuti. Jika ada masalah, lihat dokumentasi Digital Goods API.

Payment Request API

Payment Request API menangani transaksi pembayaran sebenarnya saat pembelian dilakukan. Library ini menggunakan detail item yang disediakan oleh Digital Goods API untuk melakukan pembelian dalam aplikasi menggunakan metode pembayaran yang sesuai, yang dalam kasus ini adalah Layanan Penagihan Google Play.

Mendeteksi fitur Digital Goods API

Anda dapat mendeteksi apakah Anda telah mengaktifkan API dengan benar di situs Anda melalui uji coba origin dengan memeriksa metode getDigitalGoodsService di objek window.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Menghubungkan ke layanan Penagihan Google Play

Digital Goods API dirancang agar kompatibel dengan berbagai browser dan toko digital, mirip dengan cara Payment Request API tidak bergantung pada browser dan dapat digunakan dengan berbagai penyedia pembayaran. Untuk mendapatkan instance layanan yang terkait dengan Penagihan Google Play, teruskan string "https://play.google.com/billing" sebagai metode pembayaran ke getDigitalGoodsService().

Jika metode menampilkan error, metode pembayaran Layanan Penagihan Google Play tidak tersedia (misalnya, pengguna mengakses PWA Anda melalui browser). Sebagai gantinya, Anda harus menawarkan metode pembayaran lain untuk transaksi.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Mendapatkan detail item

Setelah layanan Barang Digital terhubung ke Google Play, Anda dapat menggunakan API untuk mengambil informasi tentang produk dan pembelian.

Metode getDetails() memungkinkan Anda mendapatkan informasi tentang item yang telah disiapkan di Konsol Play. Informasi seperti judul, deskripsi, dan harga produk harus ditampilkan kepada pengguna di UI aplikasi Anda agar mereka mengetahui produk yang tersedia untuk dibeli dan harganya.

Metode getDetails() akan memerlukan daftar ID item yang sesuai dengan ID produk dari produk dalam aplikasi dan langganan yang Anda buat di Konsol Play.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Untuk mendapatkan harga yang sesuai untuk lokal pengguna, Anda perlu melakukan pemformatan tambahan:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Catatan: Digital Goods API tidak menyediakan metode untuk mendapatkan daftar ID item. Sebagai gantinya, Anda harus meng-hardcode-nya ke dalam klien atau mengambilnya dari server backend. Google Play Developer API memungkinkan Anda mengirim kueri daftar ID item dari backend. (Lihat informasi selengkapnya tentang mengimplementasikan komponen utama Layanan Penagihan Play di server backend Anda. Apa pun solusi yang Anda pilih, pastikan ID item tetap konsisten dengan yang ada di Konsol Play.

Di API v2.1, salah satu kolom yang ditampilkan oleh getDetails() adalah itemType. Ini adalah enum dengan nilai ”product” atau ”subscription” untuk menunjukkan apakah item yang sesuai adalah produk dalam aplikasi atau langganan. Kemampuan untuk membedakan antara dua jenis produk dapat berguna jika Anda perlu menerapkan perlakuan yang berbeda untuk setiap jenis produk. Misalnya, Anda mungkin memiliki halaman khusus bagi pengguna untuk berlangganan dan halaman lain untuk produk non-langganan lainnya. Hal ini juga berguna untuk mengetahui resource REST Google Play Developer API yang tepat untuk digunakan di backend Anda (purchases.products atau purchases.subscriptions).

Membeli item

Setelah produk dan detail Anda ditampilkan kepada pengguna, Anda dapat membuat alur pembelian dengan Payment Request API. Jika digunakan bersama dengan Digital Goods API, hanya satu parameter input yang diperlukan: methodData.

Layanan Penagihan Play hanya mengizinkan pembelian satu item dalam satu waktu; harga dan detail item sudah diketahui oleh server Play, sehingga parameter details tidak diperlukan. Lihat penjelasan untuk penjelasan yang lebih mendetail.

Gunakan anggota supportedMethods dari parameter methodData di PaymentRequest untuk mengidentifikasi Penagihan Google Play sebagai metode pembayaran dengan string "https://play.google.com/billing". Kemudian, di anggota data, teruskan ID item sebagai sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Kemudian, buat permintaan pembayaran dan panggil show() untuk memulai alur pembayaran:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Tindakan ini akan menampilkan UI pembelian Play kepada pengguna, tempat mereka akan melihat detail tentang produk yang mereka coba beli. Mereka dapat membatalkan transaksi atau melanjutkan pembayaran. Jika pengguna membatalkan pembayaran, promise yang ditampilkan oleh show() akan ditolak dengan error. Jika mereka berhasil membayar dan menyelesaikan pembelian, promise akan diselesaikan dengan PaymentResponse. Di properti details respons pembayaran, token pembelian ditampilkan.

Untuk mencegah penipuan, sangat penting untuk memverifikasi pembelian dan token pembelian di server backend Anda. Sebaiknya lacak juga pengguna dan token pembelian terkait mereka. Pelajari cara menerapkan verifikasi di server backend Anda.

Setelah memvalidasi pembelian, panggil complete() pada respons pembayaran untuk menyelesaikan alur pembayaran dan menutup UI penagihan. Anda juga dapat meneruskan string result opsional untuk menunjukkan status proses pembayaran. Browser yang akan memutuskan apakah akan memberikan indikasi hasil ini kepada pengguna atau tidak. Chrome tidak membuat isyarat yang terlihat oleh pengguna, jadi sebaiknya Anda menampilkan pesan error atau keberhasilan Anda sendiri di PWA Anda.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Upgrade dan downgrade langganan

Alur pembelian ini sama untuk pembelian produk dalam aplikasi dan langganan. Namun, untuk langganan, Google Play memiliki opsi pembelian tambahan yang dapat Anda terapkan: upgrade dan downgrade. Saat membuat data untuk metode pembayaran, Anda harus meneruskan hal berikut untuk memulai alur upgrade atau downgrade:

  • sku: Ini adalah ID item untuk langganan baru yang akan di-upgrade atau di-downgrade.
  • oldSku: Ini adalah ID item untuk langganan pengguna saat ini.
  • purchaseToken: Ini adalah token pembelian untuk langganan pengguna saat ini. Seperti yang disebutkan sebelumnya, sebaiknya Anda melacak token pembelian di backend. Untuk skenario ini dan skenario lainnya, Anda juga harus mengaitkan pengguna dengan pembelian dan token pembelian saat ini.
  • prorationMode: Inilah cara langganan baru akan ditagih saat menggantikan langganan pengguna saat ini.
Mode Penghitungan Prorata Deskripsi

immediateAndChargeProratedPrice

Langganan ini langsung diupgrade, dan siklus penagihannya tetap sama. Perbedaan harga untuk periode yang tersisa akan ditagihkan kepada pengguna.

immediateAndChargeFullPrice

Langganan ini diupgrade atau didowngrade dan pengguna akan langsung dikenai biaya penuh untuk hak baru. Nilai yang tersisa dari langganan sebelumnya akan dihitung secara prorata sesuai waktu untuk langganan baru. Mode prorata ini baru saja ditambahkan dalam rilis Google Play Billing Library 4.0. Sekarang tersedia melalui Bubblewrap mulai dari versi 1.13.5.

immediateWithoutProration

DINONAKTIFKAN SEMENTARA Ada potensi jalur penipuan dengan mode prorata ini di mana pengguna bisa mendapatkan langganan yang diupgrade tanpa pembayaran tambahan untuk satu siklus penagihan. Perlu diketahui bahwa kami telah menonaktifkan mode ini untuk sementara saat kami berupaya memperbaikinya.

immediateWithTimeProration

Langganan ini langsung diupgrade atau didowngrade. Semua sisa waktu disesuaikan berdasarkan perbedaan harga, dan dikreditkan ke langganan yang baru dengan memajukan tanggal penagihan berikutnya. Ini adalah perilaku default.

deferred

Langganan diupgrade atau didowngrade hanya jika langganan diperpanjang. Hal ini berguna terutama untuk downgrade.

unknownSubscriptionUpgradeDowngradePolicy

Tidak ada kebijakan yang ditetapkan. Tindakan ini tidak disarankan.

Pelajari lebih lanjut berbagai mode prorata dalam dokumentasi referensi Google Play Billing Library. Lihat dokumen developer Android untuk mengetahui informasi selengkapnya tentang upgrade dan downgrade langganan serta rekomendasi mode prorata.

Penggunaan kolom tambahan ini akan terlihat seperti ini:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Di sini, item adalah ItemDetails langganan baru yang ingin diupgrade atau didowngrade oleh pengguna, dan oldPurchase adalah PurchaseDetails langganan pengguna saat ini.

Mengonfirmasi pembelian

Setelah pengguna membeli item, Anda harus memberi mereka hak yang sesuai (akses ke item atau konten yang baru saja mereka beli). Kemudian, konfirmasi pembelian. Mengonfirmasi pembelian memberi tahu Google Play bahwa Anda telah menerima dan memproses pembelian dengan tepat.

Catatan: Jika pembelian tidak dikonfirmasi dalam waktu 72 jam setelah waktu pembelian, pembayaran akan dikembalikan dananya kepada pengguna dan pembelian akan dibatalkan. Token pembelian tidak akan lagi valid, jadi saat Anda mengirim kueri untuk pembelian yang ada, pembelian yang dibatalkan tidak akan ditampilkan. Hal ini memastikan bahwa pengguna tidak ditagih secara tidak benar jika terjadi error jaringan yang menyebabkan mereka tidak mendapatkan hak atas item mereka.

Anda harus mengonfirmasi pembelian dari server backend menggunakan Google Play Developer API. Sebaiknya berikan hak, lalu konfirmasi pembelian bersama-sama di server backend Anda.

  1. Setelah pengguna melakukan pembelian di sisi klien, kirim token pembelian dan ID item dalam permintaan ke server backend Anda.
  2. Di backend Anda, untuk mendapatkan detail tentang pembelian guna memverifikasinya, panggil:
  3. Berikan hak yang sesuai di database backend Anda.
  4. Kemudian, konfirmasi pembelian dengan memanggil:

Menggunakan pembelian

Saat Anda mengonfirmasi pembelian, Google Play akan mengetahui bahwa pengguna kini memiliki item tersebut dan tidak boleh diizinkan untuk membelinya lagi. Jika ini adalah item yang hanya perlu dibeli satu kali oleh pengguna dan akan dimiliki selamanya (misalnya, skin karakter game), maka item tersebut tidak dapat dikonsumsi.

Atau, item tersebut mungkin sesuatu yang Anda batasi agar pengguna hanya dapat memiliki satu item dalam satu waktu. Kemudian, pengguna harus menggunakan item tersebut sebelum dapat membeli item lain. Saat pengguna “menggunakan” item, untuk memberi tahu Google Play bahwa pengguna telah menggunakan item tersebut, Anda harus memanggil metode consume(). Kemudian, Google Play akan menyediakan item tersebut agar dapat dibeli lagi oleh pengguna.

Untuk item yang Anda izinkan dimiliki pengguna dalam jumlah banyak, item tersebut harus dapat dibeli berulang kali tanpa perlu digunakan terlebih dahulu (kami menyebutnya item berulang). Demikian pula, item ini harus “dikonsumsi” sebelum Google Play mengizinkan pengguna membelinya lagi. Oleh karena itu, meskipun pengguna belum menggunakan item, Anda perlu memanggil metode consume() untuk menandai item sebagai telah digunakan.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Memeriksa pembelian yang ada

Alur pengguna utama terakhir adalah memeriksa pembelian yang ada (produk dalam aplikasi yang belum digunakan dan langganan yang sedang berlangsung) untuk memberi tahu pengguna langganan atau item yang mereka miliki saat ini. Pembelian yang ada ini akan berasal dari pembelian Google Play sebelumnya di perangkat mana pun yang dilakukan dalam aplikasi atau di Play Store. Pembelian yang dilakukan dari luar aplikasi di Play Store disebut pembelian di luar aplikasi.

Saat mengambil pembelian yang ada, Anda juga harus memeriksa status konfirmasi dan mengonfirmasi pembelian yang dilakukan sebelumnya tetapi tidak dikonfirmasi dengan benar. Sebaiknya pembelian dikonfirmasi sesegera mungkin agar hak pengguna selalu terbaru dan tercermin dengan benar di aplikasi.

Metode listPurchases() Digital Goods API akan menampilkan daftar PurchaseDetails yang berisi itemId dan purchaseToken untuk setiap pembelian. Anda harus menggunakan Google Play Developer API di server backend untuk memeriksa status pembelian dan mengonfirmasinya dengan tepat. Anda harus:

  1. Panggil metode listPurchases() Digital Goods API di sisi klien untuk mengambil daftar pembelian pengguna.
  2. Untuk setiap pembelian, teruskan purchaseToken dan itemId ke backend Anda.
  3. Jika sesuai, berikan hak di database backend Anda.
  4. Kemudian, panggil:dan periksa acknowledgementState.
  5. Jika nilainya 0 (belum dikonfirmasi), panggil:

Pelajari lebih lanjut cara memverifikasi pembelian di server backend sebelum memberikan hak.

Histori pembelian

Meskipun listPurchases akan menampilkan informasi tentang pembelian yang sudah ada dari pengguna, metode listPurchaseHistory() (di v2.1 API) akan menampilkan pembelian terbaru yang dilakukan oleh pengguna untuk setiap item, terlepas dari apakah pembelian tersebut telah berakhir, dibatalkan, atau telah digunakan. Metode listPurchaseHistory() menampilkan daftar PurchaseDetails yang berisi itemId dan purchaseToken untuk setiap pembelian, yang harus Anda gunakan dengan Google Play Developer API di server backend untuk mengambil informasi selengkapnya.

Pembelian di luar aplikasi

Pembelian di luar aplikasi adalah pembelian yang tidak dilakukan dalam alur pembelian dalam aplikasi normal. Hal ini biasanya terjadi di Play Store, bukan di aplikasi Anda. Ada dua cara utama pengguna dapat melakukan pembelian di luar aplikasi:

  • Menukarkan kode promo: Di menu pengguna Play Store, di “Penawaran & notifikasi” -> “Tukarkan kode promo” atau di “Pembayaran & langganan” -> “Tukarkan kode voucher”.
  • Berlangganan ulang: Di menu pengguna Play Store, di “Pembayaran & langganan” -> “Langganan”. Di sini, pengguna dapat mengelola semua langganan mereka di berbagai aplikasi. Untuk langganan yang habis masa berlakunya atau dibatalkan, pengguna memiliki opsi untuk “Berlangganan lagi”.

Saat pengguna berlangganan lagi dari Play Store, pembelian mereka tidak dikonfirmasi secara otomatis sehingga mereka mungkin menerima pengembalian dana. Perilaku ini disengaja karena pengguna hanya akan ditagih untuk langganan mereka jika mereka membuka aplikasi untuk menggunakannya. Pengguna mungkin melihat “Konfirmasi langganan” seperti ini, yang mengingatkan mereka untuk membuka aplikasi.

Pengguna akan diminta untuk mengonfirmasi langganan mereka dengan membuka aplikasi untuk mengonfirmasi pembelian.

Anda sebagai developer yang harus menerapkan konfirmasi ini setelah pengguna meluncurkan aplikasi. Itulah sebabnya kami merekomendasikan pemeriksaan pembelian yang ada (biasanya saat aplikasi diluncurkan pertama kali) dan mengonfirmasi pembelian yang belum dikonfirmasi.

Mengizinkan pengguna mengelola langganan

Untuk pengalaman pengguna yang baik, penting untuk menyediakan cara bagi pengguna untuk mengelola dan membatalkan langganan dalam aplikasi. Sebaiknya buat deep link, di halaman atau menu setelan, yang akan mengalihkan pengguna ke halaman pengelolaan langganan Play Store untuk aplikasi Anda. Ganti URL berikut dengan “sub-product-id” dan “app-package-name” yang sesuai:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Langkah berikutnya

Alur pengguna dan cuplikan kode ini adalah penerapan dasar untuk menunjukkan cara menggunakan Digital Goods API dan Payment Request API di PWA Anda untuk menerapkan Layanan Penagihan Play. Anda harus menggunakan API sesuai dengan konteks dan kasus penggunaan aplikasi Anda. Untuk contoh penerapan menyeluruh, lihat contoh open source kami.

Kemudian, lihat cara menerapkan komponen penting Penagihan Play di server backend Anda untuk menjaga keamanan aplikasi dan selalu memperbaruinya dengan hak pengguna Anda.