Menerima Pembayaran melalui Layanan Penagihan Google Play dengan Digital Goods API dan Payment Request API

André Cipriani Bandarra
André Cipriani Bandarra
Twitter GitHub Glitch Mastodon Halaman beranda

Jika aplikasi didistribusikan melalui Google Play, dan Anda ingin menjual produk digital atau menawarkan langganan, Anda harus menggunakan Layanan Penagihan Google Play. Layanan Penagihan Google Play menawarkan alat untuk mengelola katalog, harga dan langganan, laporan yang berguna, dan alur checkout yang didukung oleh Play Store yang sudah tidak asing lagi bagi pengguna Anda.

Untuk aplikasi yang dibuat menggunakan Aktivitas Web Tepercaya, dan dikirim melalui Google Play Store, Anda kini dapat menggunakan Payment Request API dan Digital Goods API untuk berintegrasi dengan Layanan Penagihan Google Play. Tersedia di Chrome 101 dan yang lebih baru untuk Android serta ChromeOS.

Dalam panduan ini, Anda akan mempelajari cara menambahkan dukungan Layanan Penagihan Google Play ke PWA dan mengemasnya untuk didistribusikan di Google Play Store untuk ChromeOS dan Play Store.

Anda akan menggunakan dua API platform web untuk menambahkan dukungan Layanan Penagihan Play ke PWA Anda. Digital Goods API digunakan untuk mengumpulkan informasi SKU dan memeriksa pembelian serta hak dari Play Store. Payment Request API digunakan untuk mengonfigurasi Google Play Store sebagai metode pembayaran dan untuk menyelesaikan alur pembelian.

Cara memonetisasi aplikasi di Play Store

Ada dua cara monetisasi aplikasi Anda dengan Layanan Penagihan Google Play di Play Store:

  • Pembelian dalam aplikasi memungkinkan penjualan item virtual yang tahan lama dan habis pakai, seperti fitur tambahan, atau menghapus iklan.
  • Langganan, menawarkan akses berkelanjutan ke konten atau layanan kepada pengguna dengan biaya berulang, seperti langganan atau keanggotaan berita.

Persyaratan

Untuk menyiapkan Layanan Penagihan Google Play, Anda memerlukan:

Mengupdate project Bubblewrap

Jika Bubblewrap belum diinstal, Anda harus menginstalnya. Lihat Panduan Memulai Cepat untuk mengetahui detail tentang cara memulai. Jika sudah memiliki Bubblewrap, pastikan untuk mengupdate ke versi 1.8.2 atau yang lebih baru.

Bubblewrap juga memiliki fitur di balik tanda. Untuk mengaktifkannya, Anda perlu mengubah konfigurasi project di twa-manifest.json, yang terletak di root project dan mengaktifkan fitur alphaDependencies serta playBilling:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

Setelah file konfigurasi diupdate, jalankan bubblewrap update untuk menerapkan konfigurasi ke project, diikuti dengan bubblewrap build, untuk membuat paket Android baru dan mengupload paket ini ke Play Store.

Fitur yang mendeteksi ketersediaan Digital Goods API dan Layanan Penagihan Google Play

Saat ini, Digital Goods API hanya didukung oleh Chrome saat PWA dijalankan di dalam Aktivitas Web Tepercaya, dan Anda dapat mendeteksinya jika tersedia dengan memeriksa getDigitalGoodsService pada objek window:

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

Digital Goods API mungkin tersedia di semua browser dan mendukung berbagai toko. Untuk memeriksa apakah backend toko tertentu didukung, Anda harus memanggil getDigitalGoodsService() dengan meneruskan ID toko sebagai parameter. Google Play Store diidentifikasi oleh string https://play.google.com/billing:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

Mengambil detail SKU

Digital Goods API menyediakan getDetails(), yang memungkinkan pengambilan informasi seperti judul, deskripsi, dan yang terpenting, harga, dari backend pembayaran.

Anda kemudian dapat menggunakan informasi ini di antarmuka penggunaan dan memberikan detail selengkapnya kepada pengguna:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

Membuat alur pembelian

Konstruktor untuk PaymentRequest memerlukan dua parameter: daftar metode pembayaran dan daftar detail pembayaran.

Saat berada di dalam Aktivitas Web Tepercaya, Anda harus menggunakan metode pembayaran Layanan Penagihan Google Play, dengan menetapkan https://play.google.com/billing sebagai ID, dan menambahkan SKU produk sebagai anggota data:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

Meskipun detail pembayaran diperlukan, Layanan Penagihan Play akan mengabaikan nilai tersebut dan menggunakan nilai yang ditetapkan saat membuat SKU di Konsol Play sehingga dapat diisi dengan nilai palsu:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Panggil show() pada objek permintaan pembayaran untuk memulai alur pembayaran. Jika Promise berhasil, maka pembayaran mungkin berhasil. Jika gagal, pengguna mungkin membatalkan pembayaran.

Jika janji berhasil, Anda harus memverifikasi dan mengonfirmasi pembelian. Agar terlindung dari penipuan, langkah ini harus diimplementasikan menggunakan backend Anda. Lihat dokumentasi Layanan Penagihan Play untuk mempelajari cara menerapkan verifikasi di backend. Jika Anda tidak mengonfirmasi pembelian, setelah tiga hari, pengguna akan menerima pengembalian dana dan Google Play akan mencabut pembelian tersebut.

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

Secara opsional, consume() dapat dipanggil pada purchaseToken untuk menandai pembelian sebagai telah digunakan dan memungkinkan pembelian tersebut kembali.

Dengan menggabungkan semuanya, metode pembelian akan terlihat seperti berikut:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

Memeriksa status pembelian yang ada

Digital Products API memungkinkan Anda memeriksa apakah pengguna memiliki hak yang sudah ada (pembelian dalam aplikasi yang belum digunakan atau langganan yang sedang berlangsung) dari pembelian sebelumnya yang telah mereka lakukan, baik di perangkat lain, dari penginstalan sebelumnya, ditukarkan dari kode promo, atau terakhir kali mereka membuka aplikasi.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Ini adalah saat yang tepat untuk memeriksa pembelian yang sebelumnya dilakukan tetapi tidak dikonfirmasi. Sebaiknya konfirmasi pembelian sesegera mungkin untuk memastikan hak pengguna dicerminkan dengan benar di aplikasi Anda.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Menguji integrasi Anda

Di perangkat Android Pengembangan

Anda dapat mengaktifkan Digital Goods API di perangkat Android pengembangan untuk pengujian:

  • Pastikan Anda menggunakan Android 9 atau yang lebih baru dengan mode developer diaktifkan.
  • Instal Chrome 101 atau yang lebih baru.
  • Aktifkan tanda berikut di Chrome dengan membuka chrome://flags dan menelusuri tanda berikut menurut nama:
    • #enable-debug-for-store-billing
  • Pastikan situs dihosting menggunakan protokol https. Menggunakan http akan menyebabkan API menjadi undefined

Di perangkat ChromeOS

Digital Goods API akan tersedia di ChromeOS versi stabil mulai versi 89. Sementara itu, Anda dapat menguji Digital Goods API:

  • Instal aplikasi Anda dari Play Store di perangkat.
  • Pastikan situs dihosting menggunakan protokol https. Menggunakan http akan menyebabkan API menjadi undefined

Dengan pengguna uji coba dan tim UM (Uji Mutu)

Play Store menyediakan affordance untuk pengujian, termasuk akun pengujian pengguna dan SKU pengujian. Lihat dokumentasi pengujian Layanan Penagihan Google Play untuk informasi selengkapnya.

Apa langkah selanjutnya?

Seperti yang telah dibahas dalam dokumen ini, Play Billing API memiliki komponen sisi klien, yang dikelola oleh Digital Goods API, dan komponen sisi server.