Buat iOS Subscription Group

Subscription group sangat penting untuk mengatur dan mengelola berbagai level langganan di aplikasi iOS Anda. Memahami cara kerjanya sangat krusial untuk mengimplementasikan fitur upgrade, downgrade, dan crossgrade.

Apa itu Subscription Group?

Subscription group adalah kumpulan langganan terkait yang bisa dipilih oleh pengguna. Pengguna hanya bisa berlangganan satu paket dalam satu grup pada satu waktu. Saat mereka berpindah langganan, Apple akan menangani transisinya secara otomatis.

Mengapa Subscription Group Penting

Subscription group memungkinkan:

• Harga bertingkat: Menawarkan paket basic, premium, dan ultimate
• Durasi berbeda: Opsi bulanan, tahunan, dan lifetime
• Logika upgrade/downgrade: Penanganan otomatis perubahan langganan
• Manajemen yang lebih simpel: Mengelompokkan langganan terkait

Level Langganan

Dalam satu grup, setiap langganan harus diurutkan dari nilai tertinggi (level 1) ke nilai terendah. Peringkat ini menentukan bagaimana perubahan langganan diklasifikasikan:

Contoh Level

Level 1 (Nilai Tertinggi)

• Premium Tahunan ($99.99/tahun)
• Ultimate Bulanan ($19.99/bulan)

Level 2 (Nilai Menengah)

• Standard Tahunan ($49.99/tahun)
• Premium Bulanan ($9.99/bulan)

Level 3 (Nilai Terendah)

• Basic Tahunan ($29.99/tahun)
• Standard Bulanan ($4.99/bulan)

Tipe Perubahan Langganan

Apple secara otomatis menangani tiga tipe perubahan langganan berdasarkan peringkat level:

1. Upgrade

Beralih ke tier lebih tinggi langganan (misal, level 2 → level 1).

Perilaku:

• Berlaku setelahnya seketika
• User menerima pengembalian dana prorata untuk sisa waktu
• Langganan baru langsung aktif

Contoh:

// User currently has: Standard Monthly (Level 2)
// User upgrades to: Premium Annual (Level 1)
// Result: Immediate access to Premium, refund for unused Standard time

2. Downgrade

Pindah ke sebuah lower-tier (misalnya, level 1 → level 2).

Perilaku:

• Berlaku pada tanggal perpanjangan berikutnya
• Pengguna tetap menggunakan langganan saat ini hingga periode berakhir
• Langganan baru dimulai otomatis setelah masa berlaku habis

Contoh:

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

3. Crossgrade

Beralih ke langganan lain pada level tier yang sama.

Perilaku bergantung pada durasi:

Durasi Berbeda → Berperilaku seperti downgrade

• Berlaku pada tanggal perpanjangan berikutnya
• Contoh: Monthly Premium (Level 1) → Annual Premium (Level 1)

Durasi Sama → Berperilaku seperti upgrade

• Langsung berlaku saat ini juga
• Contoh: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

Membuat Grup Langganan

1. Buka Subscriptions

   Di App Store Connect, pilih aplikasi Anda dan buka Monetisasi > Langganan.

2. Buat Grup

   Klik + di sebelah “Subscription Groups” untuk membuat grup baru.

3. Beri Nama Grup

   Pilih nama deskriptif yang mencerminkan isi langganan di dalamnya:

   • “Akses Premium”
   • “Paket Cloud Storage”
   • “Fitur Pro”

4. Tambah Langganan

   Setelah grup dibuat, tambahkan langganan satu per satu. Setiap langganan akan memiliki peringkat level.

5. Atur Peringkat Level

   Urutkan langganan dari nilai tertinggi (1) ke terendah. Pertimbangkan:

   • Paket tahunan biasanya memiliki peringkat lebih tinggi dari bulanan
   • Tier harga lebih tinggi berada di atas tier harga lebih rendah
   • Tier Ultimate/premium memiliki peringkat tertinggi

Penggunaan di Aplikasi

Plugin native-purchases menangani logika subscription group secara otomatis:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Fetch all subscriptions in a group
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Display current subscription using StoreKit transactions
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const activeSubs = purchases.filter((purchase) => purchase.isActive);

// Detect pending downgrade/cancellation (StoreKit sets willCancel === true)
const pendingChange = purchases.find((purchase) => purchase.willCancel === true);
if (pendingChange) {
  console.log('Subscription will stop auto-renewing on', pendingChange.expirationDate);
}

// Purchase (StoreKit handles upgrades/downgrades automatically)
await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_annual',
  productType: PURCHASE_TYPE.SUBS,
});

// Listen for StoreKit updates (fires on upgrades/downgrades/refunds)
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription updated:', transaction);
});

Menangani Perubahan Langganan

Deteksi Tipe Perubahan

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Get current subscription info
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const currentSubscription = purchases.find(
  (purchase) => purchase.subscriptionState === 'subscribed',
);

if (currentSubscription) {
  // StoreKit reports if user cancelled auto-renew
  if (currentSubscription.willCancel) {
    console.log(
      `User cancelled. Access remains until ${currentSubscription.expirationDate}`,
    );
  }

  if (currentSubscription.isUpgraded) {
    console.log('User recently upgraded to this plan.');
  }
}

// Listen for automatic upgrades/downgrades
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription changed!', transaction);
  if (transaction.subscriptionState === 'revoked') {
    revokeAccess();
  } else if (transaction.isActive) {
    unlockPremiumFeatures();
  }
});

Komunikasi pengguna

Selalu komunikasikan perubahan perilaku dengan jelas:

Untuk Upgrade:

“Anda akan langsung mendapatkan akses ke fitur Premium. Langganan Anda saat ini akan diprorata.”

Untuk Downgrade:

“Anda tetap memiliki akses Premium hingga [tanggal perpanjangan], lalu beralih ke Standard.”

Untuk Crossgrade:

“Paket Anda akan berubah ke penagihan Tahunan pada perpanjangan berikutnya tanggal [tanggal].”

Monitoring Server

Gunakan App Store Server Notifications v2 dari Apple atau backend validasi receipt Anda sendiri untuk menyinkronkan perubahan StoreKit ke database Anda. Pasangkan server notifications dengan transactionUpdated listener agar client dan backend tetap sinkron.

Praktik Terbaik

Organisasi Grup

• Kelompokkan langganan terkait dalam grup yang sama
• Jangan campur fitur yang tidak relevan (misal: storage dan hapus iklan)
• Buat grup terpisah untuk set fitur yang berbeda

Strategi Ranking Level

• Paket tahunan → Level lebih tinggi dari bulanan (untuk tier yang sama)
• Tier harga lebih tinggi → Level lebih tinggi
• Pertimbangkan nilai manfaat, bukan hanya harga

Pengalaman Pengguna

• Tampilkan langganan saat ini dengan jelas
• Tampilkan semua opsi yang tersedia di grup
• Tandai perubahan mana yang langsung berlaku vs. saat perpanjangan
• Izinkan pindah antar paket dengan mudah

Pengujian

• Uji semua skenario upgrade
• Uji semua skenario downgrade
• Verifikasi perilaku crossgrade
• Cek webhook terpicu

Skenario Umum

Skenario 1: Paket Bulanan Tiga Tingkat

Level 1: Ultimate Monthly ($19.99)
Level 2: Premium Monthly ($9.99)
Level 3: Basic Monthly ($4.99)

• Basic → Premium: Upgrade (langsung)
• Premium → Ultimate: Upgrade (langsung)
• Ultimate → Premium: Downgrade (saat perpanjangan)
• Basic → Ultimate: Upgrade (langsung)

Skenario 2: Paket Durasi Campuran

Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)

• Bulanan → Tahunan: Crossgrade (saat perpanjangan)
• Tahunan → Bulanan: Downgrade (saat perpanjangan)

Skenario 3: Multi-Tingkat Multi-Durasi

Level 1: Ultimate Annual ($199/year)
Level 2: Ultimate Monthly ($19.99/month)
Level 3: Premium Annual ($99/year)
Level 4: Premium Monthly ($9.99/month)
Level 5: Basic Annual ($49/year)
Level 6: Basic Monthly ($4.99/month)

Setup ini memberikan fleksibilitas maksimal dengan logika upgrade/downgrade yang jelas.

Pemecahan Masalah

Langganan tidak muncul di grup:

• Pastikan sudah ditugaskan ke grup yang benar
• Pastikan statusnya minimal “Ready to Submit”
• Pastikan product ID sudah benar

Perilaku upgrade/downgrade salah:

• Tinjau peringkat level (1 = tertinggi)
• Pastikan tier langganan sudah sesuai
• Cek apakah level sudah diatur dengan benar

Produk dari grup yang berbeda:

• User bisa berlangganan ke beberapa grup sekaligus
• Ini disengaja - simpan produk terkait di grup yang sama

getActiveProducts menampilkan beberapa langganan:

• Cek apakah langganan berada di grup berbeda
• Pastikan user tidak berlangganan via Family Sharing
• Tinjau status langganan di App Store Connect

Sumber daya tambahan

Untuk detail lebih lanjut, lihat dokumentasi resmi Apple tentang subscription groups.

Lanjutkan dari Membuat Grup Langganan iOS

Jika Anda menggunakan Buat iOS Subscription Group untuk merencanakan persetujuan store dan distribusi, hubungkan dengan Menggunakan @capgo/native-purchases untuk kemampuan native saat menggunakan @capgo/native-purchases, @capgo/capacitor-in-app-review untuk detail implementasi di @capgo/capacitor-in-app-review, Menggunakan @capgo/capacitor-in-app-review untuk kapabilitas native di bagian Menggunakan @capgo/capacitor-in-app-review, @capgo/capacitor-native-market untuk detail implementasi di @capgo/capacitor-native-market, dan Menggunakan @capgo/capacitor-native-market untuk kapabilitas native di Menggunakan @capgo/capacitor-native-market.