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

André Cipriani Bandarra

Jika aplikasi Anda 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, serta alur checkout yang didukung oleh Play Store yang sudah dikenal pengguna Anda.

Untuk aplikasi yang dibuat menggunakan Aktivitas Web Tepercaya, dan dikirim melalui Google Play Store, Anda sekarang dapat menggunakan Payment Request API dan Digital Goods API untuk berintegrasi dengan Layanan Penagihan Google Play. Fitur ini tersedia di Chrome 101 dan yang lebih baru untuk Android dan 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. 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 agar aplikasi Anda dapat memonetisasi dengan Penagihan Google Play di Play Store:

  • Pembelian dalam aplikasi memungkinkan penjualan konten virtual tahan lama dan habis pakai, seperti fitur tambahan, atau penghapusan 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 belum menginstal Bubblewrap, Anda harus menginstalnya. Lihat Panduan Memulai Cepat untuk mengetahui detail tentang cara memulai. Jika Anda sudah memiliki Bubblewrap, pastikan untuk mengupdate ke versi 1.8.2 atau yang lebih baru.

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

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

Setelah file konfigurasi diperbarui, 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

Digital Goods API saat ini hanya didukung oleh Chrome saat PWA dijalankan di dalam Trusted Web Activity, dan Anda dapat mendeteksi apakah API tersebut tersedia dengan memeriksa getDigitalGoodsService pada objek window:

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

Digital Goods API mungkin tersedia di browser apa pun dan mendukung berbagai toko. Untuk memeriksa apakah backend toko tertentu didukung, Anda harus memanggil getDigitalGoodsService() yang 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 untuk SKU

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

Kemudian, Anda 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 menggunakan dua parameter: daftar metode pembayaran dan daftar detail pembayaran.

Saat berada di dalam Aktivitas Web Tepercaya, Anda harus menggunakan metode pembayaran 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, 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, pembayaran mungkin berhasil. Jika gagal, pengguna kemungkinan membatalkan pembayaran.

Jika janji berhasil, Anda harus memverifikasi dan mengonfirmasi pembelian. Untuk melindungi dari penipuan, langkah ini harus diterapkan menggunakan backend Anda. Lihat dokumentasi Layanan Penagihan Play untuk mempelajari cara menerapkan verifikasi di backend Anda. Jika Anda tidak mengonfirmasi pembelian, setelah tiga hari, pengguna akan menerima pengembalian dana dan Google Play akan membatalkan 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 sudah habis dan memungkinkannya dibeli lagi.

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 Goods API memungkinkan Anda memeriksa apakah pengguna memiliki hak yang 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 hanya saat 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 juga merupakan waktu yang tepat untuk memeriksa pembelian yang sebelumnya dilakukan, tetapi tidak dikonfirmasi. Sebaiknya konfirmasi pembelian sesegera mungkin untuk memastikan hak pengguna ditampilkan 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 berdasarkan namanya:
    • #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 stabil mulai versi 89. Sementara itu, Anda dapat menguji Digital Goods API:

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

Dengan pengguna pengujian dan tim QA

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

Mau ke mana berikutnya?

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