Panduan integrasi dalam aplikasi untuk program penawaran eksternal

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

Penyiapan Play Billing Library

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

Menghubungkan ke Google Play

Langkah-langkah pertama dalam proses integrasi sama dengan langkah-langkah yang dijelaskan dalam panduan integrasi penagihan, dengan beberapa modifikasi saat melakukan inisialisasi BillingClient:

  • Anda perlu memanggil metode baru untuk menunjukkan bahwa Anda ingin menggunakan penawaran eksternal: enableExternalOffer.

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

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

Memeriksa ketersediaan

Aplikasi Anda harus mengonfirmasi bahwa penawaran eksternal tersedia dengan memanggil isExternalOfferAvailableAsync.

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

Kotlin


billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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 dibuat dari Play Billing Library. Token transaksi eksternal baru harus dibuat setiap kali pengguna mengunjungi situs eksternal melalui API penawaran eksternal. Hal ini dapat dilakukan dengan memanggil API createExternalOfferReportingDetailsAsync. Token ini harus dibuat tepat sebelum pengguna diarahkan ke luar aplikasi. Token tidak boleh di-cache dan token baru harus dibuat setiap kali pengguna diarahkan ke luar aplikasi.

Kotlin


billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java


billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Dialog informasi untuk pengguna

Untuk berintegrasi dengan penawaran eksternal, aplikasi Anda yang memenuhi syarat harus menampilkan layar informasi yang membantu pengguna memahami bahwa mereka akan diarahkan ke luar aplikasi ke situs eksternal. Layar informasi harus ditampilkan kepada pengguna dengan memanggil showExternalOfferInformationDialog API sebelum menautkan ke penawaran eksternal setiap kali diperlukan.

Kotlin


// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java


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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

Jika metode ini menampilkan BillingResponseCode.OK, aplikasi Anda dapat melanjutkan untuk mengarahkan pengguna ke situs eksternal. Jika metode ini menampilkan BillingResponseCode.USER_CANCELED, aplikasi Anda tidak boleh melanjutkan membuka situs.

Melaporkan transaksi ke Google Play

Semua transaksi eksternal harus dilaporkan ke Google Play dengan memanggil Google Play Developer API dari backend Anda. Transaksi eksternal harus dilaporkan sambil memberikan externalTransactionToken yang diperoleh menggunakan createExternalOfferReportingDetailsAsync 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 isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync, dan showExternalOfferInformationDialog mungkin menampilkan respons selain BillingResponseCode.OK. Pertimbangkan untuk menangani kode respons ini sebagai berikut:

  • ERROR: Ini adalah error internal. Jangan lanjutkan transaksi atau membuka situs web eksternal. Coba lagi dengan memanggil showExternalOfferInformationDialog() untuk menampilkan dialog informasi kepada pengguna saat Anda mencoba mengarahkan pengguna ke luar aplikasi lagi.
  • FEATURE_NOT_SUPPORTED: API penawaran eksternal tidak didukung oleh Play Store di perangkat saat ini. Jangan lanjutkan transaksi atau membuka situs web eksternal.
  • USER_CANCELED: Jangan lanjutkan membuka situs eksternal. Panggil showExternalOfferInformationDialog() lagi untuk menampilkan dialog informasi kepada pengguna 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 terjadi karena pengguna tidak berada di negara yang memenuhi syarat untuk program ini atau akun Anda belum berhasil terdaftar dalam program ini. Jika masalahnya yang terakhir, 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. Dalam kasus SERVICE_DISCONNECTED, buat kembali koneksi dengan Google Play sebelum mencoba lagi.

Uji penawaran eksternal

Penguji lisensi harus digunakan untuk menguji integrasi penawaran eksternal Anda. Anda tidak akan ditagih untuk transaksi yang telah dimulai oleh akun penguji lisensi. Lihat Menguji penagihan via Google Play 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.