Panduan integrasi dalam aplikasi untuk link konten eksternal

Dokumen ini menjelaskan cara mengintegrasikan API Play Billing Library untuk menawarkan link konten eksternal di aplikasi yang memenuhi syarat. Hal ini mencakup kemampuan untuk menautkan pengguna di Amerika Serikat ke luar aplikasi Play Anda untuk memberikan penawaran kepada pengguna terkait konten digital dalam aplikasi dan download aplikasi. Untuk mempelajari program ini lebih lanjut, lihat persyaratan program.

Penyiapan Play Billing Library

Tambahkan dependensi Play Billing Library ke aplikasi Android. Untuk menggunakan API link eksternal, Anda harus menggunakan versi 8.2 atau yang lebih tinggi. Jika Anda perlu bermigrasi dari versi sebelumnya, ikuti petunjuk dalam panduan migrasi sebelum menambahkan link konten eksternal.

Melakukan inisialisasi klien penagihan

Untuk melakukan inisialisasi klien penagihan, ikuti langkah-langkah yang sama seperti yang dijelaskan dalam Melakukan inisialisasi BillingClient dengan modifikasi berikut:

  • Jangan aktifkan PurchasesUpdatedListener - pendengar ini tidak diperlukan untuk link konten eksternal.
  • Panggil enableBillingProgram() dengan BillingProgram.EXTERNAL_CONTENT_LINK untuk menunjukkan bahwa aplikasi Anda menggunakan link konten eksternal.

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

Kotlin

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

Java

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

Menghubungkan ke Google Play

Setelah melakukan inisialisasi BillingClient, hubungkan ke Google Play seperti yang dijelaskan dalam Menghubungkan ke Google Play.

Memeriksa kelayakan pengguna

Setelah terhubung ke Google Play, Anda harus memeriksa apakah pengguna memenuhi syarat untuk program link konten eksternal dengan memanggil metode isBillingProgramAvailableAsync(). Metode ini menampilkan BillingResponseCode.OK jika pengguna memenuhi syarat untuk program link konten eksternal. Contoh berikut menunjukkan cara memeriksa kelayakan pengguna untuk link konten eksternal:

Kotlin

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

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

Lihat bagian penanganan respons untuk mengetahui detail tentang cara aplikasi Anda merespons kode respons lainnya. Jika menggunakan ekstensi Kotlin, Anda dapat menggunakan coroutine Kotlin sehingga tidak perlu menentukan pemroses terpisah.

Menyiapkan token transaksi eksternal

Selanjutnya, Anda harus membuat token transaksi eksternal dari Play Billing Library. Token transaksi eksternal baru harus dibuat setiap kali pengguna mengunjungi situs eksternal melalui API link eksternal. Hal ini dapat dilakukan dengan memanggil API createBillingProgramReportingDetailsAsync. Token harus dibuat tepat sebelum pengguna keluar dari penautan.

Catatan: Token transaksi eksternal tidak boleh di-cache dan Anda harus membuat token baru setiap kali pengguna dialihkan.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
      }
  });

Jika menggunakan ekstensi Kotlin, Anda dapat menggunakan coroutine Kotlin sehingga tidak perlu menentukan pemroses terpisah.

Membuka link eksternal

Setelah token transaksi eksternal siap, pengguna dapat ditautkan ke luar aplikasi ke penawaran konten digital atau download aplikasi dengan memanggil metode launchExternalLink. Google Play mungkin merender dialog informasi tambahan kepada pengguna, bergantung pada setelan pengguna saat Anda memanggil API ini.

Saat memanggil metode launchExternalLink, detail link eksternal harus diberikan melalui LaunchExternalLinkParams. Class ini berisi parameter berikut:

  • URI link - Link ke situs eksternal tempat konten digital atau download aplikasi ditawarkan. Untuk download aplikasi, link ini harus didaftarkan dan disetujui di Konsol Play.
  • Jenis Link - Jenis konten yang ditawarkan kepada pengguna.
  • Mode Peluncuran - Menentukan cara link diluncurkan. Untuk download aplikasi, Anda harus menyetelnya ke LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Program Penagihan - Setel ini ke BillingProgram.EXTERNAL_CONTENT_LINK.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .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.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Penanganan respons

Saat terjadi error, metode isBillingProgramAvailableAsync(), dan createBillingProgramReportingDetailsAsync(), dan onLaunchExternalLinkResponse() dapat memberikan BillingResponseCode 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 API lagi atau dengan memanggil launchExternalLink() pada saat Anda mencoba mengarahkan pengguna ke luar aplikasi.
  • FEATURE_NOT_SUPPORTED: API link konten 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 saat Anda mencoba mengarahkan pengguna ke luar aplikasi.
  • BILLING_UNAVAILABLE: Transaksi tidak memenuhi syarat untuk link konten eksternal sehingga tidak 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 link konten 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.