Panduan integrasi dalam aplikasi untuk penagihan alternatif dengan pilihan pengguna

Panduan ini menjelaskan cara mengintegrasikan API untuk menawarkan penagihan alternatif dengan pilihan pengguna di aplikasi Anda.

Penyiapan Play Billing Library

Tambahkan dependensi Play Billing Library ke aplikasi Android. Untuk menggunakan API penagihan alternatif, Anda harus menggunakan versi 5.2 atau yang lebih tinggi. Jika Anda perlu bermigrasi dari versi sebelumnya, ikuti petunjuk dalam panduan migrasi sebelum Anda mencoba menerapkan penagihan alternatif.

Menghubungkan ke Google Play

Langkah-langkah pertama dalam proses integrasi sama dengan langkah-langkah yang dijelaskan di Panduan integrasi Layanan Penagihan Google Play, dengan beberapa modifikasi saat melakukan inisialisasi BillingClient Anda:

• Anda perlu memanggil metode baru untuk menunjukkan bahwa Anda ingin menawarkan pilihan opsi penagihan kepada pengguna: enableUserChoiceBilling.
• Anda harus mendaftarkan UserChoiceBillingListener untuk menangani kasus ketika pengguna memilih penagihan alternatif.

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

Menampilkan produk yang tersedia

Anda dapat menampilkan produk yang tersedia kepada pengguna dengan cara yang sama seperti integrasi sistem Layanan penagihan Google Play. Setelah pengguna melihat produk yang tersedia untuk dibeli dan memilih produk yang akan dibeli, luncurkan alur penagihan sesuai pilihan pengguna seperti yang dijelaskan di bagian berikut.

Meluncurkan alur penagihan sesuai pilihan pengguna

Luncurkan alur penagihan sesuai pilihan pengguna dengan memanggil launchBillingFlow(). Cara kerjanya sama seperti meluncurkan alur pembelian dengan integrasi sistem Layanan penagihan Google Play: Anda memberikan instance ProductDetails dan offerToken yang sesuai dengan produk dan penawaran yang ingin didapatkan pengguna. Jika pengguna memilih sistem penagihan Google Play, informasi ini akan digunakan untuk melanjutkan alur pembelian.

Saat developer memanggil launchBillingFlow(), sistem Layanan penagihan Google Play akan menjalankan pemeriksaan berikut:

• Sistem akan memeriksa apakah negara Google Play pengguna adalah negara yang mendukung penagihan alternatif dengan pilihan pengguna (yaitu negara yang didukung). Jika negara Google Play pengguna didukung, Google Play akan memeriksa apakah penagihan alternatif telah diaktifkan berdasarkan konfigurasi BillingClient.
  • Jika penagihan alternatif dengan pilihan pengguna telah diaktifkan, alur pembelian akan menampilkan UX pilihan pengguna.
  • Jika penagihan alternatif dengan pilihan pengguna tidak diaktifkan, alur pembelian akan menampilkan UX sistem layanan penagihan Google Play standar, tanpa pilihan pengguna.
• Jika negara Google Play pengguna bukan negara yang didukung, alur pembelian akan menampilkan UX sistem layanan penagihan Google Play standar, tanpa pilihan pengguna.

Menangani pilihan pengguna

Cara Anda menangani alur pembelian lainnya berbeda-beda bergantung pada apakah pengguna memilih sistem penagihan Google Play atau sistem penagihan alternatif.

Saat pengguna memilih sistem penagihan alternatif

Jika pengguna memilih sistem penagihan alternatif, Google Play akan memanggil UserChoiceBillingListener untuk memberi tahu aplikasi bahwa aplikasi perlu meluncurkan alur pembelian dalam sistem penagihan alternatif. Secara khusus, metode userSelectedAlternativeBilling() dipanggil.

Token transaksi eksternal yang diberikan dalam objek UserChoiceDetails mewakili tanda tangan bagi pilihan pengguna untuk memasuki alur penagihan alternatif. Gunakan token ini untuk melaporkan transaksi apa pun yang dihasilkan dari pilihan ini, seperti yang dijelaskan dalam panduan integrasi backend.

UserChoiceBillingListener harus melakukan tindakan berikut:

• Mendapatkan produk yang dibeli oleh pengguna sehingga dapat ditampilkan dalam alur pembelian di sistem penagihan alternatif.
• Mengumpulkan string yang diterima sebagai token transaksi eksternal dan kirimkan ke backend Anda untuk mempertahankannya. Nantinya, ini akan digunakan untuk melaporkan transaksi eksternal ke Google Play jika pengguna menyelesaikan pembelian khusus ini.
• Meluncurkan alur pembelian alternatif developer.

Jika pengguna menyelesaikan pembelian menggunakan sistem penagihan alternatif, Anda harus melaporkan transaksi ke Google Play dengan memanggil Google Play Developer API dari backend Anda dalam waktu 24 jam, dengan memberikan externalTransactionToken dan detail transaksi tambahan. Lihat panduan integrasi backend untuk detail selengkapnya.

Contoh berikut menunjukkan cara menerapkan UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Saat pengguna memilih sistem penagihan Google Play

Jika pengguna memilih sistem penagihan Google Play, mereka akan melanjutkan pembelian melalui Google Play.

• Lihat Memproses pembelian dalam panduan integrasi library untuk mengetahui informasi lebih lanjut tentang cara menangani pembelian dalam aplikasi baru melalui sistem penagihan Google Play.
• Lihat Langganan baru dalam panduan pengelolaan langganan untuk mendapatkan panduan tambahan tentang pembelian langganan.

Menangani perubahan pada langganan

Untuk developer yang menggunakan penagihan alternatif dengan pilihan pengguna, pembelian harus diproses melalui sistem penagihan Google Play atau dilaporkan dengan externalTransactionId, bergantung pada pilihan pengguna. Perubahan pada langganan yang ada dan diproses melalui alur pilihan pengguna dapat dilakukan melalui sistem penagihan yang sama hingga masa berlakunya habis.

Bagian ini menjelaskan cara menangani beberapa skenario perubahan langganan yang umum.

Alur upgrade dan downgrade

Perubahan paket langganan termasuk alur upgrade dan downgrade harus ditangani secara berbeda bergantung pada apakah langganan tersebut awalnya dibeli melalui sistem penagihan Google Play atau melalui sistem penagihan alternatif.

Add-on yang bergantung pada langganan yang ada, menggunakan metode pembayaran yang sama, dan biaya berulang yang selaras ditangani sebagai upgrade. Untuk add-on lainnya, pengguna harus dapat memilih sistem penagihan mana yang ingin mereka gunakan. Mulai tugas baru pengalaman pembelian Anda dengan menggunakan launchBillingFlow(), seperti yang dijelaskan di Meluncurkan alur penagihan sesuai pilihan pengguna.

Langganan yang dibeli melalui sistem penagihan alternatif

Untuk langganan yang awalnya dibeli melalui sistem penagihan alternatif developer setelah pilihan pengguna, pengguna yang meminta upgrade atau downgrade harus melanjutkan melalui sistem penagihan alternatif developer tanpa melalui pengalaman pilihan pengguna lagi.

Untuk melakukannya, panggil launchBillingFlow() saat pengguna meminta upgrade atau downgrade. Gunakan setOriginalExternalTransactionId, bukan menetapkan objek SubscriptionUpdateParams dalam parameter, untuk memberikan ID transaksi eksternal bagi pembelian asli. Cara ini tidak menampilkan layar pilihan pengguna, dikarenakan pilihan pengguna untuk pembelian asli dipertahankan untuk upgrade dan downgrade. Dalam skenario ini, panggilan ke launchBillingFlow() menghasilkan token transaksi eksternal baru untuk transaksi yang dapat Anda ambil dari callback.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Setelah upgrade atau downgrade dilakukan dalam sistem penagihan alternatif, Anda harus melaporkan transaksi baru menggunakan token transaksi eksternal yang diperoleh melalui panggilan sebelumnya untuk pembelian langganan baru.

Langganan yang dibeli melalui sistem penagihan Google Play

Demikian pula, pengguna yang membeli langganan mereka saat ini melalui sistem penagihan Google Play setelah pilihan pengguna akan melihat alur upgrade atau downgrade di sistem penagihan Google Play. Petunjuk berikut menjelaskan cara meluncurkan alur pembelian untuk upgrade atau downgrade melalui sistem penagihan Google Play:

1. Identifikasi offerToken dari penawaran yang dipilih untuk paket baru:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. Kirim informasi yang benar ke sistem penagihan Google Play untuk memproses pembelian baru, termasuk token pembelian untuk langganan yang ada:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Pembelian ini dilanjutkan di sistem penagihan Google Play, dan aplikasi Anda akan menerima panggilan PurchasesUpdatedListener.onPurchaseUpdated dengan hasil pembelian. Jika pembelian berhasil, metode onPurchaseUpdated() juga menerima informasi pembelian baru, dan backend Anda akan menerima Notifikasi Developer Real Time SUBSCRIPTION_PURCHASED. Saat mengambil status untuk pembelian baru, atribut linkedPurchaseToken akan ditautkan ke pembelian langganan lama, sehingga Anda dapat menghentikannya seperti yang direkomendasikan.

Pembatalan dan pemulihan langganan

Pengguna harus dapat membatalkan langganan mereka kapan saja. Saat pengguna membatalkan langganan, penghentian hak dapat ditangguhkan hingga periode berbayar berakhir. Misalnya, jika pengguna membatalkan langganan bulanan pada pertengahan bulan, mereka dapat terus mengakses layanan selama sisa ~2 minggu hingga aksesnya dihapus. Selama periode ini, langganan masih aktif secara teknis, sehingga pengguna dapat menggunakan layanan.

Tidak jarang pengguna memutuskan untuk membatalkan pembatalan selama periode aktif ini. Dalam panduan ini, hal ini disebut pemulihan. Bagian berikut menjelaskan cara menangani skenario pemulihan dalam integrasi API penagihan alternatif Anda.

Langganan yang dibeli melalui sistem penagihan alternatif

Jika memiliki ID transaksi eksternal untuk langganan yang dibatalkan, Anda tidak perlu memanggil launchBillingFlow() untuk memulihkan langganan, sehingga tidak boleh digunakan untuk jenis aktivasi ini. Jika pengguna memulihkan langganan mereka saat masih dalam periode aktif langganan yang dibatalkan, tidak ada transaksi yang terjadi pada saat itu. Anda dapat terus melaporkan perpanjangan saat siklus saat ini berakhir dan perpanjangan berikutnya terjadi. Hal ini mencakup kasus saat pengguna menerima kredit atau harga perpanjangan khusus sebagai bagian dari pemulihan (misalnya, promosi untuk mendorong pengguna agar melanjutkan langganannya).

Langganan yang dibeli melalui sistem penagihan Google Play

Umumnya, pengguna dapat memulihkan langganan di sistem penagihan Google Play. Untuk langganan yang dibatalkan yang awalnya dibeli di sistem penagihan Google Play, pengguna dapat memilih untuk mengurungkan pembatalan saat langganan masih aktif melalui fitur Berlangganan lagi Google Play. Dengan begitu, Anda akan menerima Notifikasi Developer Real Time SUBSCRIPTION_RESTARTED di backend Anda, dan token pembelian baru tidak diterbitkan—token asli akan digunakan untuk melanjutkan langganan. Untuk mempelajari cara mengelola pemulihan di sistem penagihan Google Play, lihat Pemulihan di panduan pengelolaan langganan.

Anda juga dapat memicu pemulihan di sistem penagihan Google Play dari aplikasi dengan memanggil launchBillingFlow(). Lihat Sebelum akhir masa berlaku langganan - dalam aplikasi untuk mendapatkan penjelasan tentang cara melakukannya. Dalam kasus pengguna yang melalui alur pilihan pengguna untuk pembelian asli (yang dibatalkan tetapi masih aktif), sistem akan otomatis mendeteksi pilihan pengguna dan menampilkan antarmuka pengguna untuk memulihkan pembelian ini. Mereka diminta untuk mengonfirmasi pembelian kembali langganan melalui Google Play, tetapi tidak perlu melalui alur pilihan pengguna lagi. Dalam hal ini, token pembelian baru akan dikeluarkan untuk pengguna. Backend Anda akan menerima Notifikasi Developer Real Time SUBSCRIPTION_PURCHASED, dan nilai linkedPurchaseToken untuk status pembelian baru akan ditetapkan seperti dalam kasus upgrade atau downgrade, dengan token pembelian lama untuk langganan yang dibatalkan.

Berlangganan lagi

Jika langganan benar-benar berakhir, baik karena pembatalan atau penolakan pembayaran tanpa pemulihan (penangguhan akun yang telah habis masa berlakunya), pengguna harus berlangganan lagi jika ingin memulai ulang hak.

Berlangganan lagi juga dapat diaktifkan melalui aplikasi dengan memprosesnya seperti halnya pendaftaran standar. Pengguna harus dapat memilih sistem penagihan yang ingin mereka gunakan. Dalam kasus ini, launchBillingFlow() dapat dipanggil, seperti yang dijelaskan di Meluncurkan alur penagihan sesuai pilihan pengguna.

Menguji penagihan alternatif

Penguji lisensi harus digunakan untuk menguji integrasi penagihan alternatif 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.