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 memanggilshowExternalOfferInformationDialog()
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. PanggilshowExternalOfferInformationDialog()
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 kasusSERVICE_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.