Panduan integrasi dalam aplikasi untuk program penawaran eksternal

Panduan ini menjelaskan cara mengintegrasikan dengan API untuk mendukung penawaran eksternal di aplikasi dan wilayah yang memenuhi syarat. Untuk mempelajari lebih lanjut program penawaran eksternal, termasuk persyaratan kelayakan dan cakupan geografis, lihat persyaratan program.

Penyiapan Play Billing Library

Untuk menggunakan API penawaran eksternal, tambahkan dependensi Play Billing Library versi 8.2 atau yang lebih tinggi ke aplikasi Android Anda. Jika Anda perlu bermigrasi dari versi sebelumnya, ikuti petunjuk dalam panduan migrasi sebelum Anda mencoba menerapkan penawaran eksternal.

Menghubungkan ke Google Play

Langkah-langkah pertama dalam proses integrasi sama dengan langkah-langkah yang dijelaskan dalam panduan integrasi penagihan, kecuali Anda harus memanggil enableBillingProgram untuk menunjukkan bahwa Anda ingin menggunakan penawaran eksternal saat melakukan inisialisasi BillingClient:

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

Setelah melakukan inisialisasi BillingClient, Anda harus menghubungkan ke Google Play seperti yang dijelaskan dalam panduan integrasi.

Periksa ketersediaan

Untuk mengonfirmasi bahwa penawaran eksternal tersedia bagi pengguna saat ini, panggil isBillingProgramAvailableAsync.

API ini menampilkan BillingResponseCode.OK jika penawaran eksternal tersedia. Lihat penanganan respons untuk mengetahui detail tentang cara aplikasi Anda merespons kode respons lainnya.

Kotlin


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingResult: BillingResult,
      billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
      }
  })

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }
  });

Menyiapkan token transaksi eksternal

Untuk melaporkan transaksi eksternal ke Google Play, Anda harus memiliki token transaksi eksternal yang dihasilkan dari Play Billing Library. Anda bisa mendapatkan token ini dengan memanggil API createBillingProgramReportingDetailsAsync. Token baru harus dibuat tepat sebelum mengarahkan pengguna ke luar aplikasi untuk setiap penawaran eksternal. Token tidak boleh di-cache di seluruh transaksi.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Atau, Anda dapat membuat kueri fungsi penangguhan createBillingProgramReportingDetailsAsync dengan ekstensi Kotlin sehingga Anda tidak perlu menentukan pemroses:

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

Meluncurkan alur penawaran eksternal

Untuk memulai alur penawaran eksternal, aplikasi Anda yang memenuhi syarat harus memanggil API launchExternalLink() dari thread utama aplikasi Anda. API ini mengambil input objek LaunchExternalLinkParams. Untuk membuat objek LaunchExternalLinkParams, gunakan class LaunchExternalLinkParams.Builder. Class ini berisi parameter berikut:

  • linkUri - Link ke situs eksternal tempat konten digital atau download aplikasi ditawarkan. Untuk download aplikasi, link ini harus didaftarkan dan disetujui di Konsol Play.
  • linkType - Jenis konten yang ditawarkan kepada pengguna.
  • launchMode - Menentukan cara link diluncurkan. Untuk download aplikasi, Anda harus menyetelnya ke LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram - Setel ini ke BillingProgram.EXTERNAL_OFFER.

Saat Anda memanggil launchExternalLink(), dialog informasi tambahan mungkin ditampilkan kepada pengguna berdasarkan setelan pengguna mereka. Bergantung pada parameter launchMode, Play akan meluncurkan URI link di browser eksternal atau mengembalikan alur ke aplikasi Anda untuk meluncurkan URI. Dalam kebanyakan kasus, Anda dapat menggunakan mode LAUNCH_IN_EXTERNAL_BROWSER_OR_APP tempat Play akan meluncurkan URI untuk Anda. Jika Anda ingin memiliki perilaku yang lebih disesuaikan, seperti meluncurkan URI di webview atau membuka URI di browser tertentu, Anda dapat menggunakan mode CALLER_WILL_LAUNCH_LINK. Untuk melindungi privasi pengguna, pastikan tidak ada informasi identitas pribadi (PII) yang diteruskan dalam URI.

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
  .setLaunchMode(
    LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
  .build();

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
      if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Jika Anda menyetel LaunchMode ke CALLER_WILL_LAUNCH_LINK, Anda harus mengarahkan pengguna ke luar aplikasi hanya jika onLaunchExternalLinkResponse menyediakan BillingResponseCode.OK.

Melaporkan transaksi ke Google Play

Anda harus melaporkan semua transaksi eksternal ke Google Play dengan memanggil Google Play Developer API dari backend Anda. Saat melaporkan transaksi, Anda harus memberikan externalTransactionToken yang diperoleh dari createBillingProgramReportingDetailsAsync API. Jika pengguna melakukan beberapa pembelian, Anda dapat menggunakan externalTransactionToken yang sama untuk melaporkan setiap pembelian. Untuk mempelajari cara melaporkan transaksi, lihat panduan integrasi backend.

Penanganan respons

Jika terjadi error, metode isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), dan launchExternalLink() dapat menampilkan respons selain BillingResponseCode.OK. Pertimbangkan untuk menangani kode respons ini sebagai berikut:

  • ERROR: Ini adalah error internal. Jangan lanjutkan transaksi atau membuka situs eksternal. Coba lagi dengan memanggil launchExternalLink() untuk menampilkan dialog informasi kepada pengguna saat Anda mencoba mengarahkan pengguna ke luar aplikasi pada waktu berikutnya.
  • FEATURE_NOT_SUPPORTED: API penawaran eksternal tidak didukung oleh Play Store di perangkat saat ini. Jangan lanjutkan transaksi atau membuka situs eksternal.
  • USER_CANCELED: Jangan lanjutkan membuka situs eksternal. Panggil launchExternalLink() lagi untuk menampilkan dialog informasi kepada pengguna pada saat Anda mencoba mengarahkan pengguna ke luar aplikasi.
  • BILLING_UNAVAILABLE: Transaksi tidak memenuhi syarat untuk penawaran eksternal sehingga tidak boleh dilanjutkan dalam program ini. Hal ini disebabkan karena pengguna tidak berada di negara yang memenuhi syarat untuk program ini atau akun Anda belum berhasil terdaftar dalam program ini. Jika disebabkan oleh pendaftaran belum berhasil, periksa status pendaftaran Anda di Konsol Play.
  • DEVELOPER_ERROR: Terjadi error dengan permintaan. Gunakan pesan debug untuk mengidentifikasi dan memperbaiki error sebelum melanjutkan.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Ini adalah error sementara yang harus ditangani dengan kebijakan percobaan ulang yang sesuai. Jika SERVICE_DISCONNECTED ditampilkan, buat kembali koneksi dengan Google Play sebelum mencoba lagi.

Menguji penawaran eksternal

Penguji lisensi harus digunakan untuk menguji integrasi penawaran eksternal Anda. Anda tidak akan menerima invoice untuk transaksi yang telah dimulai oleh akun penguji lisensi. Lihat Menguji penagihan dalam aplikasi dengan pemberian lisensi aplikasi untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi penguji lisensi.

Langkah berikutnya

Setelah menyelesaikan integrasi dalam aplikasi, Anda siap untuk mengintegrasikan backend.