Mulai Membuat

Pemasangan

Anda dapat menggunakan Setup Bantuan AI untuk memasang plugin. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah berikut:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/native-purchases` plugin in my project.

Jika Anda lebih suka Setup Manual, pasang plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

1. Install the package

   bun add @capgo/native-purchases

2. Sinkronisasi dengan proyek native

   bunx cap sync

3. Periksa dukungan billing

   import { NativePurchases } from '@capgo/native-purchases';
   
   const { isBillingSupported } = await NativePurchases.isBillingSupported();
   if (!isBillingSupported) {
     throw new Error('Billing is not available on this device');
   }

4. Muat produk secara langsung dari toko

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const { products } = await NativePurchases.getProducts({
     productIdentifiers: [
       'com.example.premium.monthly',
       'com.example.premium.yearly',
       'com.example.one_time_unlock'
     ],
     productType: PURCHASE_TYPE.SUBS, // Use PURCHASE_TYPE.INAPP for one‑time products
   });
   
   products.forEach((product) => {
     console.log(product.title, product.priceString);
   });

5. Implementasikan alur pembelian dan pengembalian

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const monthlyPlanId = 'monthly-plan'; // Base Plan ID from Google Play Console
   
   const transaction = await NativePurchases.purchaseProduct({
     productIdentifier: 'com.example.premium.monthly',
     planIdentifier: monthlyPlanId,        // REQUIRED for Android subscriptions, ignored on iOS
     productType: PURCHASE_TYPE.SUBS,
     quantity: 1,
   });
   
   console.log('Transaction ID', transaction.transactionId);
   
   await NativePurchases.restorePurchases();

   Rencana komitmen bulanan iOS

   Jika langganan iOS yang didukung kembali pricingTermsUntuk menampilkan opsi pembayaran bulanan dengan komitmen 12 bulan dan melewati billingPlanType: 'monthly' ke purchaseProduct(). Lihat rencana pembayaran bulanan iOS dengan komitmen untuk alur lengkap.

   iOS
   • Buat produk dalam aplikasi dan langganan di App Store Connect.
     
   • Pakai StoreKit Local Testing atau Sandbox tester untuk QA.
     
   • Tidak perlu edit manifest. Pastikan produk Anda disetujui.
   Android
   • Buat produk dalam aplikasi dan langganan di Google Play Console.
     
   • Unggah setidaknya versi uji internal dan tambahkan tester lisensi.
     
   • Tambahkan izin pembayaran ke AndroidManifest.xml:

   <uses-permission android:name="com.android.vending.BILLING" />

Contoh layanan pembelian

import { NativePurchases, PURCHASE_TYPE, Transaction } from '@capgo/native-purchases';
import { Capacitor } from '@capacitor/core';

class PurchaseService {
  private premiumProduct = 'com.example.premium.unlock';
  private monthlySubId = 'com.example.premium.monthly';
  private monthlyPlanId = 'monthly-plan'; // Base Plan ID (Android only)

  async initialize() {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) throw new Error('Billing unavailable');

    const { products } = await NativePurchases.getProducts({
      productIdentifiers: [this.premiumProduct, this.monthlySubId],
      productType: PURCHASE_TYPE.SUBS,
    });

    console.log('Loaded products', products);

    if (Capacitor.getPlatform() === 'ios') {
      NativePurchases.addListener('transactionUpdated', (transaction) => {
        this.handleTransaction(transaction);
      });
    }
  }

  async buyPremium(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.premiumProduct,
      productType: PURCHASE_TYPE.INAPP,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async buyMonthly(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.monthlySubId,
      planIdentifier: this.monthlyPlanId, // REQUIRED for Android subscriptions
      productType: PURCHASE_TYPE.SUBS,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async restore() {
    await NativePurchases.restorePurchases();
    await this.refreshEntitlements();
  }

  async openManageSubscriptions() {
    await NativePurchases.manageSubscriptions();
  }

  private async processTransaction(transaction: Transaction) {
    this.unlockContent(transaction.productIdentifier);
    this.validateOnServer(transaction).catch(console.error);
  }

  private unlockContent(productIdentifier: string) {
    // persist entitlement locally
    console.log('Unlocked', productIdentifier);
  }

  private async refreshEntitlements() {
    const { purchases } = await NativePurchases.getPurchases({
      productType: PURCHASE_TYPE.SUBS,
    });
    console.log('Current purchases', purchases);
  }

  private async handleTransaction(transaction: Transaction) {
    console.log('StoreKit transaction update:', transaction);
    await this.processTransaction(transaction);
  }

  private async validateOnServer(transaction: Transaction) {
    await fetch('/api/validate-purchase', {
      method: 'POST',
      body: JSON.stringify({
        transactionId: transaction.transactionId,
        receipt: transaction.receipt,
        purchaseToken: transaction.purchaseToken,
      }),
    });
  }
}

Pilihan pembelian yang diperlukan

Pilihan	Platform	Deskripsi
productIdentifier	iOS + Android	SKU/ID Produk yang telah dikonfigurasi di App Store Connect / Google Play Console.
productType	Hanya untuk Android	PURCHASE_TYPE.INAPP atau PURCHASE_TYPE.SUBSDengan nilai default INAPPSelalu tetapkan SUBS Selalu tetapkan ke
planIdentifier	untuk langganan.	ID Paket Dasar dari Google Play Console. Diperlukan untuk langganan, diabaikan pada iOS dan pembelian dalam aplikasi.
billingPlanType	langiappanan subscripti iOS	Rencana pembayaran StoreKit untuk pembelian. Gunakan 'monthly' Rencana pembayaran StoreKit untuk pembelian. Gunakan product.pricingTerms mengungkapkan pilihan tersebut.
quantity	iOS	Only for pembelian dalam aplikasi, default ke 1. Android selalu membeli satu item.
appAccountToken	Halaman iOS + Android	UUID/teks yang menghubungkan pembelian ke pengguna Anda. Diperlukan untuk UUID di iOS; Android menerima string yang dienkripsi hingga 64 karakter.
isConsumable	Halaman Android	Dipasang ke true untuk mengonsumsi token secara otomatis setelah memberikan hak untuk konsumables. Default ke false.

Mengecek status hak

Pakai getPurchases() untuk melihat ulang transaksi setiap toko melaporkan:

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

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

purchases.forEach((purchase) => {
  if (purchase.isActive && purchase.expirationDate) {
    console.log('iOS sub active until', purchase.expirationDate);
  }

  const isAndroidIapValid =
    ['PURCHASED', '1'].includes(purchase.purchaseState ?? '') && purchase.isAcknowledged;

  if (isAndroidIapValid) {
    console.log('Grant in-app entitlement for', purchase.productIdentifier);
  }
});

Perilaku Platform

• IOS: Langganan termasuk isActive, expirationDate, willCancel, dan dukungan pendengar StoreKit 2. Pembelian dalam aplikasi memerlukan validasi bukti penerimaan server.
• Android: isActive/expirationDate tidak diisi; panggil Google Play Developer API dengan purchaseToken untuk status otoritatif. purchaseState wajib PURCHASED dan isAcknowledged wajib true.

API quick reference

• isBillingSupported() – periksa ketersediaan StoreKit / Google Play.
• getProduct() / getProducts() – ambil harga, judul lokal, deskripsi, tawaran intro, dan istilah harga iOS yang didukung.
• purchaseProduct() – mulai aliran pembelian StoreKit 2 atau Billing klien, termasuk rencana pembayaran bulanan iOS.
• restorePurchases() – ulangi pembelian sejarah dan sinkron ke perangkat saat ini.
• getPurchases() – daftar semua transaksi iOS atau pembelian Play Billing.
• manageSubscriptions() – buka UI manajemen langganan native.
• addListener('transactionUpdated') – tangani transaksi StoreKit 2 yang menunggu ketika aplikasi Anda dimulai (hanya iOS).

Praktik terbaik

1. Tampilkan harga toko – Apple memerlukan menampilkan product.title dan product.priceString; jangan pernah mengkodekan secara keras.
2. Pilih appAccountToken – menghasilkan UUID (v5) secara deterministik dari ID pengguna Anda untuk menghubungkan pembelian ke akun.
3. Validasi di server – kirim receipt (iOS) / purchaseToken (Android) ke backend Anda untuk verifikasi.
4. Tangani kesalahan dengan sopan – periksa pembatalan pengguna, gagal jaringan, dan lingkungan pembayaran yang tidak mendukung.
5. Uji secara menyeluruh Ikuti langkah-langkah Petunjuk Panduan Sandbox iOS dan Petunjuk Panduan Sandbox Android.
6. Tindakan Restorasi dan Pengelolaan Penawaran – tambahkan tombol UI yang terhubung ke restorePurchases() dan manageSubscriptions().

Langkah-Langkah Pendapatan

Setelah alur pembelian berfungsi, gunakan Kit Permainan Pendapatan untuk merencanakan funnel pembayaran pertama: skop produk, ASO, harga, penempatan paywall, analisis, dan feedback pengurangan.

Troubleshooting

Produk tidak dimuat

• Pastikan ID Paket / ID Aplikasi sesuai dengan pengaturan toko.
• Konfirmasi bahwa ID produk aktif dan disetujui (App Store) atau diaktifkan (Google Play).
• Tunggu beberapa jam setelah membuat produk; penyebaran toko tidak instan.

Pembelian dibatalkan atau terjebak

• Users can cancel mid-flow; wrap calls in try/catch dan tampilkan pesan kesalahan yang ramah pengguna.
• Untuk Android, pastikan akun uji instal aplikasi dari Play Store (track internal) agar Billing berfungsi.
• Cek logcat/Xcode untuk kesalahan billing saat menjalankan di perangkat.

Keadaan langganan tidak benar

• Gunakan getPurchases() Untuk membandingkan data toko dengan cache hak lokal Anda.
• On Android, selalu tanyakan ke Google Play Developer API dengan purchaseToken untuk mendapatkan tanggal kedaluwarsa atau status pengembalian.
• On iOS, periksa isActive/expirationDate dan validasi tagihan untuk mendeteksi pengembalian atau pembatalan.

Teruskan dari Getting Started

Jika Anda menggunakan Mulai Menggunakan untuk merencanakan persetujuan toko dan distribusi, hubungkannya dengan Menggunakan @capgo/native-purchases untuk kemampuan native di Menggunakan @capgo/native-purchases, di @capgo/capacitor-ulasan-dalam-aplikasi untuk detail implementasi di @capgo/capacitor-ulasan-dalam-aplikasi, Menggunakan @capgo/capacitor-ulasan-dalam-aplikasi untuk kemampuan asli di Menggunakan @capgo/capacitor-ulasan-dalam-aplikasi, @capgo/capacitor-pasar-asli untuk detail implementasi di @capgo/capacitor-pasar-asli, dan Menggunakan @capgo/capacitor-pasar-asli untuk kemampuan asli di Menggunakan @capgo/capacitor-pasar-asli.