Langganan dengan add-on

Langganan dengan add-on memungkinkan Anda menggabungkan beberapa produk langganan yang dapat dibeli, ditagih, dan dikelola bersama. Langganan katalog produk yang ada dapat ditawarkan dengan lancar sebagai add-on tanpa spesifikasi di muka atau konfigurasi tambahan. Anda dapat meluncurkan alur pembelian dengan beberapa produk langganan yang sudah ada, dan menjualnya sebagai add-on.

Pertimbangan

Pertimbangkan poin-poin berikut saat menggunakan fitur langganan dengan add-on:

• Langganan dengan add-on hanya didukung untuk paket dasar dengan perpanjangan otomatis.

• Semua item dalam pembelian harus memiliki periode penagihan berulang yang sama. Misalnya, Anda tidak dapat memiliki langganan yang ditagih setiap tahun dengan add-on yang ditagih setiap bulan.

• Anda dapat memiliki maksimum 50 item dalam langganan dengan pembelian add-on.

• Fitur ini tidak tersedia di wilayah India (IN) dan Korea Selatan (KR).

Melakukan integrasi dengan Play Billing Library

Bagian ini menjelaskan cara mengintegrasikan fitur langganan dengan add-on dengan Play Billing Library (PBL). Panduan ini mengasumsikan bahwa Anda sudah memahami langkah-langkah integrasi PBL awal seperti, menambahkan dependensi PBL ke aplikasi Anda, melakukan inisialisasi BillingClient, dan menghubungkan ke Google Play. Bagian ini berfokus pada aspek integrasi PBL yang khusus untuk langganan dengan add-on.

Meluncurkan alur pembelian

Untuk meluncurkan alur pembelian langganan dengan add-on, lakukan langkah-langkah berikut:

1. Ambil semua item langganan Anda menggunakan metode BillingClient.queryProductDetailsAsync.

2. Tetapkan objek ProductDetailsParams untuk setiap item.

   Item yang diwakili oleh objek ProductDetailsParams, menentukan ProductDetails yang menunjukkan item langganan, dan offerToken yang memilih base plan langganan tertentu atau offer.

3. Tentukan detail item dalam metode BillingFlowParams.Builder.setProductDetailsParamsList. Class BillingFlowParams menentukan detail alur pembelian.

   Contoh berikut menunjukkan cara meluncurkan alur penagihan untuk pembelian langganan dengan beberapa item:

   Java

      BillingClient billingClient = …;
   
       // ProductDetails obtained from queryProductDetailsAsync().
       ProductDetailsParams productDetails1 = ...;
       ProductDetailsParams productDetails2 = ...;
       ArrayList productDetailsList = new ArrayList<>();
       productDetailsList.add(productDetails1);
       productDetailsList.add(productDetails2);
   
       BillingFlowParams billingFlowParams =
           BillingFlowParams.newBuilder()
              .setProductDetailsParamsList(productDetailsList)
              .build();
       billingClient.launchBillingFlow(billingFlowParams);

Aturan yang berlaku untuk item dalam pembelian

• Untuk memastikan tanggal perpanjangan add-on akhirnya selaras dengan item dasar, Google Play dapat menyisipkan biaya prorata setelah fase uji coba atau harga perkenalan.
• Kelayakan penawaran akan dievaluasi secara terpisah untuk setiap item.

Memproses pembelian

Pemrosesan langganan dengan add-on sama dengan pemrosesan pembelian item tunggal seperti yang dijelaskan dalam Mengintegrasikan Google Play Billing Library ke aplikasi Anda. Satu-satunya perbedaan adalah pengguna dapat menerima beberapa hak dengan satu pembelian. Pembelian langganan dengan add-on menampilkan beberapa item yang dapat diambil menggunakan Purchase.getProducts() di Library Layanan Penagihan Google Play, lalu daftar lineItems di purchases.subscriptionsv2.get dari Google Play Developer API.

Mengubah langganan dengan add-on

Setiap perubahan pada langganan Anda dengan add-on akan menghasilkan upgrade atau downgrade. Untuk mengetahui informasi selengkapnya, lihat mengupgrade atau menurunkan versi langganan.

Untuk mengubah atau memulihkan pembelian langganan dengan add-on yang ada di aplikasi Anda, Anda harus memanggil API launchBillingFlow dengan parameter tambahan, dan memastikan hal berikut:

• Selalu panggil setOldPurchaseToken dengan token pembelian langganan saat ini.
• Untuk mengupgrade, mendowngrade, atau melakukan crossgrade item, panggil SubscriptionProductReplacementParams.setReplacementMode untuk menentukan cara perubahan paket harus ditangani antara item pembelian lama dan baru. Jika tidak, Anda tidak perlu menyetel parameter ini.
• Saat item dasar tidak diubah, Anda masih dapat memanggil SubscriptionProductReplacementParams.setSubscriptionReplacementMode untuk menerapkan perilaku penggantian tertentu. Untuk aturan yang berlaku dalam kasus ini, lihat Berlangganan lagi atau beralih paket dalam langganan yang sama.
• Add-on baru akan segera diterapkan dengan tagihan prorata agar tanggal perpanjangan berikutnya selaras dengan item dasar dalam langganan.
• Add-on yang dihapus akan berakhir pada akhir periode penagihan saat ini.
• Saat meluncurkan alur penagihan, Anda harus menentukan semua item aktif dalam langganan dengan add-on, kecuali item yang akan dihapus, beserta add-on baru.

Contoh berikut menunjukkan cara memanggil API launchBillingFlow saat mengubah pembelian langganan yang ada dengan add-on:

BillingClient billingClient = …;

int replacementMode =…;

// ProductDetails obtained from queryProductDetailsAsync().
ProductDetailsParams productDetails1 = ...;
ProductDetailsParams productDetails2 = ...;
ProductDetailsParams productDetails3 = ...;

ArrayList newProductDetailsList = new ArrayList<>();
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setSubscriptionUpdateParams(
          SubscriptionUpdateParams.newBuilder()
              .setOldPurchaseToken(purchaseTokenOfExistingSubscription)
              // No need to set if change does not affect the base item.
             .setSubscriptionReplacementMode(replacementMode)
             .build())
        .setProductDetailsParamsList(productDetailsList)
        .build();

billingClient.launchBillingFlow(billingFlowParams);

Skenario modifikasi langganan

Tabel berikut mencantumkan berbagai skenario modifikasi untuk langganan dengan add-on, dan perilaku yang sesuai.

Saat menggunakan SubscriptionProductReplacementParams

Saat menggunakan SubscriptionUpdateParams

Notifikasi developer real time

Kolom subscriptionId tidak disediakan di RTDN untuk pembelian langganan dengan add-on, yang berisi beberapa hak item. Sebagai gantinya, Anda dapat menggunakan Play Developer API untuk mendapatkan pembelian dan melihat hak item terkait.

Perubahan harga untuk pelanggan lama

Mengubah harga langganan untuk pelanggan lama langganan dengan pembelian add-on mirip dengan mengubah harga langganan item tunggal seperti yang dijelaskan dalam Mengubah harga langganan. Namun, ada beberapa batasan dan perbedaan fungsional seperti yang dijelaskan di bagian ini.

Mengakhiri kohor harga lama

Mengakhiri kelompok lama juga memengaruhi pembelian langganan dengan add-on. Aturan berikut berlaku:

• Semua kenaikan harga dengan persetujuan pengguna yang belum disetujui harus memiliki waktu perpanjangan yang sama dengan harga baru. Jika item dalam pembelian langganan dengan add-on memiliki kenaikan harga dengan persetujuan pengguna yang belum dikonfirmasi oleh pengguna, setiap kenaikan harga dengan persetujuan pengguna baru untuk item lain dalam pembelian akan diabaikan kecuali jika menghasilkan waktu perpanjangan penerapan harga baru yang sama dengan kenaikan harga yang ada dalam status BELUM SELESAI. Setelah pengguna mengonfirmasi kenaikan harga, perubahan harga yang lebih baru akan didaftarkan. Selain itu, pengguna hanya dapat menyetujui semua kenaikan harga dengan persetujuan pengguna yang belum dikonfirmasi sekaligus.

  Contoh:

  • Pertimbangkan langganan dengan add-on (item A dan B), yang diperpanjang pada tanggal 7 setiap bulan.
  • Item A memiliki migrasi harga yang sedang berlangsung dari $7 menjadi $10, dan kenaikan harga diperkirakan akan berlaku pada 7 Juli.
  • Migrasi harga baru dari $5 menjadi $6, dimulai untuk item B pada 2 Juni. Karena kenaikan harga dengan persetujuan pengguna dimulai 37 hari setelah migrasi, kenaikan harga paling awal untuk item B akan terjadi pada 7 Agustus.

  Dalam skenario ini, hingga pengguna menyetujui perubahan harga untuk item A (hingga berada dalam status CONFIRMED), perubahan harga untuk item B tidak terdaftar untuk pembelian langganan ini, dan SubscriptionPurchaseV2 tidak menampilkan detail perubahan harga untuk item B. Setelah pengguna mengonfirmasi perubahan harga untuk item A, perubahan harga item B akan dimulai. Pengguna menerima kenaikan harga dengan persetujuan pengguna untuk item B hanya setelah menyetujui kenaikan harga dengan persetujuan pengguna untuk item A.

• Email Google Play berisi daftar semua item dengan kenaikan atau penurunan harga yang berlaku pada hari yang sama.

Membatalkan langganan dengan add-on

Pengguna dapat membatalkan seluruh pembelian langganan dengan add-on di Pusat Langganan Play, dan Anda hanya dapat membatalkan seluruh pembelian langganan dengan add-on menggunakan Google Play Developer API.

Jika pembelian langganan dibatalkan tanpa dicabut, tidak ada item dalam pembelian yang akan diperpanjang otomatis, tetapi pengguna akan terus memiliki akses ke item yang berhak hingga akhir periode penagihan yang sesuai.

Mencabut dan mengembalikan dana langganan dengan add-on

Berikut adalah beberapa panduan untuk membatalkan dan mengembalikan dana langganan:

• Gunakan Konsol Play untuk melakukan pengembalian dana berbasis jumlah untuk Pesanan tertentu tanpa mencabut akses ke langganan.

• Panggil orders.refund untuk mengembalikan dana sepenuhnya pembayaran langganan tertentu yang telah dilakukan pengguna tanpa mencabut akses ke langganan.

• Panggil purchases.subscriptionsv2.revoke untuk segera mencabut akses ke semua item langganan. Dengan API ini, Anda dapat:

  • Mencabut akses ke semua item dan memberikan pengembalian dana pro-rata.

  • Saat mencabut langganan dengan add-on menggunakan pengembalian dana prorata, pengembalian dana akan diberikan untuk pesanan terbaru setiap item dengan jumlah prorata berdasarkan waktu yang tersisa hingga perpanjangan berikutnya.

  • Cabut akses untuk semua item dan berikan FullRefund.

  • Mencabut akses item tertentu dengan pengembalian dana penuh untuk item tersebut.

Mencabut item satu per satu dalam langganan dengan add-on

Untuk mencabut item langganan tertentu dalam langganan dengan add-on tanpa mencabut seluruh pembelian, panggil purchases.subscriptionsv2.revoke dengan kolom ItemBasedRefund yang ditetapkan di RevocationContext. productId item yang harus dicabut dan dikembalikan dananya dapat ditetapkan di kolom ItemBasedRefund.

Kolom ItemBasedRefund dapat ditetapkan untuk pembelian dengan satu atau beberapa item langganan perpanjangan otomatis.

• Jika masih ada item aktif yang tersisa dalam pembelian langganan setelah mencabut item yang ditentukan dalam ItemBasedRefund, hanya item tersebut yang akan dicabut, dan dikembalikan dananya sepenuhnya tanpa mengganggu status langganan.
• Jika tidak ada item aktif yang tersisa dalam pembelian langganan setelah membatalkan item yang ditentukan dalam ItemBasedRefund, item tersebut akan dibatalkan, dikembalikan dananya sepenuhnya, dan langganan dibatalkan.

Pertimbangan

• Saat menggunakan ItemBasedRefund, hanya satu item yang dapat dibatalkan sekaligus. Permintaan dapat dipanggil beberapa kali jika item yang berbeda perlu dibatalkan.
• Jika pembelian langganan berada dalam salah satu status pembayaran ditolak, atau item yang ditentukan dalam ItemBasedRefund tidak dimiliki atau telah habis masa berlakunya, penolakan item akan diblokir.
• Penghentian item tidak didukung dalam langganan prabayar.

Masa berlaku item selama penolakan pembayaran

Untuk pembelian langganan dengan add-on, perpanjangan tertentu mungkin hanya perlu memperpanjang subset hak item, tanpa memengaruhi item dengan tanggal habis masa berlaku di masa mendatang.

Terlepas dari item mana yang terlibat dalam perpanjangan, jika pembayaran perpanjangan ditolak, pembelian langganan secara keseluruhan akan memasuki masa tenggang dan penangguhan akun seperti yang dijelaskan dalam dokumentasi berikut.

Pemilihan periode pemulihan

Karena masa tenggang itu sendiri masih memberikan hak kepada pengguna, saat pembelian langganan dengan add-on, pembayaran perpanjangan ditolak, item dengan masa tenggang minimum di semua item aktif akan dipilih, dan masa tenggang serta periode penangguhan akunnya sebagai periode pemulihan akan diterapkan untuk perpanjangan ini.

Item aktif mencakup item yang aktif dalam pembelian langganan dengan add-on tepat sebelum upaya perpanjangan, tidak termasuk item yang baru ditambahkan (yang tidak akan berhak hingga setelah pemulihan), dan tidak termasuk item yang tidak lagi aktif karena penghapusan atau penghentian.

Setelan penangguhan akun item dengan masa tenggang minimum yang dipilih akan diterapkan. Jika ada lebih dari satu item dengan masa tenggang minimum, tetapi periode penangguhan akun yang berbeda, periode penangguhan akun terpanjang akan diterapkan.

Masa tenggang

Jika pembayaran perpanjangan langganan ditolak, pembelian langganan akan memasuki status masa tenggang. Selama masa tenggang, pengguna akan terus memiliki akses ke semua item aktif dari periode perpanjangan sebelumnya. Setelah masa tenggang, jika metode pembayaran belum diperbaiki, seluruh pembelian langganan akan ditangguhkan. Jika ada item lain yang mencapai tanggal perpanjangannya selama masa tenggang, upaya penagihan baru akan dimulai untuk item tersebut setelah langganan pulih dari penolakan pembayaran.

Penangguhan akun

Selama pembelian langganan ditangguhkan, akses ke semua item langganan akan ditangguhkan hingga pembayaran dipulihkan.

Jika langganan yang ditangguhkan akun dipulihkan, pembelian langganan akan tetap ada seperti sebelumnya. Jika langganan tidak dipulihkan, item yang pembayarannya ditolak akan berakhir, dan akses ke item lainnya akan dilanjutkan selama sisa periode penagihannya.

Contoh:

• Pengguna memiliki langganan Paket Dasar Saya yang diperpanjang pada tanggal 1 setiap bulan, lalu pada 15 Agustus, menambahkan Paket add-on seharga $10 per bulan dengan uji coba gratis selama tujuh hari. Kedua item tidak menetapkan masa tenggang, dan keduanya memiliki periode penangguhan akun 30 hari.

• Pada 22 Agustus, pengguna ditagih $2,90 (10*9/31) untuk prorata hingga 31 Agustus, tetapi metode pembayaran pengguna berakhir sebelum itu, dan langganan mengalami penolakan pembayaran pada 22 Agustus.

Saat langganan memasuki penangguhan akun karena penolakan pembayaran, pengguna tidak memiliki akses ke item apa pun dalam langganan dengan add-on. Sisa waktu untuk item yang tidak diperpanjang akan dikembalikan kepada pengguna saat langganan keluar dari penangguhan akun, baik karena pembayaran telah dipulihkan atau dibatalkan.

Pada contoh sebelumnya, langganan memasuki penangguhan akun pada 22 Agustus.

• Jika akun dipulihkan pada 25 Agustus, sebelum tanggal perpanjangan yang lebih luas pada 1 September, pengguna akan mendapatkan kembali akses ke Paket Dasar Saya dan Paket add-on pada hari yang sama. Tanggal penagihan berikutnya diubah menjadi 4 September.

• Jika akun tidak dipulihkan setelah 30 hari, langganan akan dibatalkan pada 21 September dan pengguna akan kehilangan akses ke Paket add-on, dan melanjutkan akses ke Paket Dasar Saya hingga 30 September.

Dalam contoh ini, Anda harus mendapatkan expiryTime yang diperbarui untuk SEMUA item dalam langganan dengan add-on, karena beberapa item dapat melanjutkan haknya setelah masa tenggang dan penangguhan akun.

Pelaporan dan rekonsiliasi keuangan

Gunakan Laporan penghasilan untuk mencocokkan langganan aktif Anda dengan transaksi di Play. Setiap item baris transaksi memiliki ID pesanan. Dengan pembelian yang mewakili beberapa item, laporan Penghasilan dan Perkiraan penjualan akan menyertakan baris terpisah untuk setiap transaksi seperti penagihan, biaya, pajak, dan pengembalian dana, untuk setiap item yang terlibat.

Untuk dasbor di Konsol Play:

• Statistik pendapatan yang ditampilkan di bagian Pelaporan keuangan di konsol dikelompokkan menurut item.

• Pengelolaan pesanan mencerminkan pembelian langganan dengan add-on, dan menampilkan daftar per item dari apa yang dibeli. Dari pengelolaan pesanan, Anda dapat membatalkan akses, membatalkan, atau mengembalikan dana sepenuhnya untuk pembelian pengguna.