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 lebih lanjut program penawaran eksternal termasuk persyaratan kelayakan dan cakupan geografis. persyaratan program.

Penyiapan Play Billing Library

Untuk menggunakan API penawaran eksternal, menambahkan 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 Anda mencoba menerapkannya penawaran eksternal.

Menghubungkan ke Google Play

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

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

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

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

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

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

Periksa ketersediaan

Aplikasi Anda harus mengonfirmasi bahwa penawaran eksternal tersedia dengan menelepon isExternalOfferAvailableAsync

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

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.
})

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 yang dibuat dari Play Billing Library. Eksternal baru token transaksi harus dibuat setiap kali pengguna mengunjungi situs Anda melalui API penawaran eksternal. Hal ini dapat dilakukan dengan memanggil metode API createExternalOfferReportingDetailsAsync. Token ini harus yang dibuat tepat sebelum pengguna diarahkan ke luar aplikasi. Seharusnya tidak pernah di-cache dan yang baru harus dibuat setiap kali pengguna diarahkan di luar aplikasi.

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.
    }
})

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 informasi yang membantu pengguna memahami bahwa mereka akan diarahkan ke luar aplikasi ke situs web eksternal. Layar informasi harus ditampilkan kepada pengguna dengan memanggil showExternalOfferInformationDialog API sebelum menautkannya ke penawaran eksternal.

// 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)

// 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 ke mengarahkan pengguna ke situs web eksternal. Jika metode menampilkan BillingResponseCode.USER_CANCELED, aplikasi Anda tidak boleh terus membuka situs Anda.

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 saat memberikan externalTransactionToken diperoleh menggunakan API createExternalOfferReportingDetailsAsync. Jika pengguna membuat beberapa pembelian, Anda dapat menggunakan externalTransactionToken untuk melaporkan setiap pembelian. Untuk mempelajari cara melaporkan transaksi, lihat panduan integrasi backend.

Penanganan respons

Saat terjadi error, metode isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync dan showExternalOfferInformationDialog mungkin menampilkan respons selain BillingResponseCode.OK. Pertimbangkan untuk menangani kode respons ini seperti berikut:

• ERROR: Ini adalah error internal. Jangan lanjutkan dengan transaksi atau membuka situs web eksternal. Coba lagi dengan memanggil showExternalOfferInformationDialog() untuk menampilkan informasi kepada pengguna saat Anda mencoba mengarahkan pengguna ke luar .
• FEATURE_NOT_SUPPORTED: API penawaran eksternal tidak didukung oleh Play Store di perangkat saat ini. Jangan lanjutkan dengan transaksi atau membuka situs web eksternal.
• USER_CANCELED: Tidak melanjutkan membuka situs eksternal. Telepon showExternalOfferInformationDialog() lagi untuk menampilkan informasi kepada pengguna saat Anda mencoba mengarahkan pengguna ke luar aplikasi.
• BILLING_UNAVAILABLE: Transaksi tidak memenuhi syarat untuk penawaran eksternal dan karenanya tidak boleh melanjutkan program ini. Hal ini disebabkan pengguna tidak berada di negara yang memenuhi syarat untuk program ini atau akun Anda memiliki belum berhasil terdaftar dalam program. Jika yang terakhir adalah, 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 yang bersifat sementara yang harus ditangani dengan kebijakan percobaan ulang yang sesuai. Jika terjadi 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 penguji lisensi menggunakan akun layanan. Lihat Menguji penagihan via Google Play dengan pemberian lisensi aplikasi untuk informasi selengkapnya informasi tentang cara mengonfigurasi penguji lisensi.

Langkah berikutnya

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