Getting Started

Pemasangan

Anda dapat menggunakan Pengaturan Bantu AI kami untuk menginstal 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 Pengaturan Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

1. Pasang paket ini

   bun add @capgo/native-purchases

2. Sinkron 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 & restorasi

   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 pricingTermsanda dapat menampilkan opsi pembayaran bulanan dengan komitmen 12 bulan dan melewati billingPlanType: 'monthly' ke purchaseProduct(). Lihat rencana pembayaran bulanan komitmen iOS untuk alur lengkap.

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

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

Contoh pembelian layanan

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,
      }),
    });
  }
}

Opsi pembelian yang diperlukan

Opsi	Platform	Deskripsi
productIdentifier	iOS + Android	Kode SKU/ID Produk yang terkonfigurasi di App Store Connect / Google Play Console.
productType	Hanya Android	PURCHASE_TYPE.INAPP atau PURCHASE_TYPE.SUBS. Defaultnya adalah INAPP. Selalu ditetapkan sebagai SUBS untuk langganan.
planIdentifier	Langganan Android	ID Rencana Dasar dari Google Play Console. Diperlukan untuk langganan, diabaikan pada iOS dan pembelian dalam aplikasi.
billingPlanType	Langganan iOS	Rencana pembayaran StoreKit untuk pembelian. Gunakan 'monthly' untuk tagihan bulanan dengan komitmen 12 bulan ketika product.pricingTerms mengekspos opsi tersebut.
quantity	iOS	Hanya untuk pembelian dalam aplikasi, default ke 1. Android selalu membeli item satu.
appAccountToken	iOS + Android	UUID/nilai string yang menghubungkan pembelian ke pengguna Anda. Diperlukan untuk UUID di iOS; Android menerima string yang dienkripsi hingga 64 karakter.
isConsumable	Android	Ditetapkan ke true untuk mengonsumsi token secara otomatis setelah memberikan hak untuk konsumables. Default ke false.

Mengecek status hak

Gunakan getPurchases() untuk tampilan lintas platform dari setiap transaksi yang dilaporkan oleh toko-toko:

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);
  }
});

Tindakan platform

• iOS: Langganan termasuk isActive, expirationDate, willCancel, dan dukungan pemantauan StoreKit 2. Pembelian dalam aplikasi memerlukan validasi bukti penerimaan server.
• Android: isActive/expirationDate tidak diisi; hubungi pengembang Google Play Developer API untuk status yang otoritatif. purchaseToken harus dipenuhi; purchaseState dapat dipenuhi; PURCHASED dan isAcknowledged wajib ada true.

API referensi cepat

• isBillingSupported() – periksa ketersediaan StoreKit / Google Play.
• getProduct() / getProducts() – ambil harga, judul yang disesuaikan dengan lokasi, deskripsi, tawaran intro, dan istilah harga iOS yang didukung.
• purchaseProduct() – mulai alur 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 antarmuka pengelolaan 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; tidak pernah mengkodekan secara keras.
2. Pakai appAccountToken – generate UUID (v5) secara deterministik dari ID pengguna 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, kegagalan jaringan, dan lingkungan pembayaran yang tidak didukung.
5. Test secara menyeluruh – ikuti panduan sandbox iOS dan panduan sandbox Android Tawarkan pengembalian dan manajemen.
6. – tambahkan tombol UI yang terhubung ke dan restorePurchases() Langkah-Langkah Pendapatan Selanjutnya manageSubscriptions().

Judul bagian “Langkah-Langkah Pendapatan Selanjutnya”

__CAPGO_KEEP_0__ Pedoman Pendapatan Untuk merencanakan funnel pembayaran pertama Anda: skop produk, ASO, harga, penempatan paywall, analisis, dan umpan balik pengurangan.

Pengaturan Masalah

Produk tidak terbuka

• Pastikan ID bundle / ID aplikasi sesuai dengan konfigurasi toko.
• Konfirmasikan 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

• Pengguna dapat membatalkan di tengah alur; tutup panggilan dengan try/catch dan permukaan pesan kesalahan yang ramah.
• Untuk Android, pastikan akun uji instal aplikasi dari Play Store (track internal) sehingga Billing berfungsi.
• Periksa logcat/Xcode untuk kesalahan billing ketika menjalankan pada perangkat.

Status langganan salah

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

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan persetujuan toko dan distribusi, hubungkannya dengan Menggunakan @capgo/native-purchases untuk kemampuan asli dalam Menggunakan @capgo/native-purchases, @capgo/capacitor-in-app-review untuk detail implementasi dalam @capgo/capacitor-in-app-review, Menggunakan @capgo/capacitor-in-app-review untuk kemampuan asli dalam Menggunakan @capgo/capacitor-in-app-review, @capgo/capacitor-native-market untuk detail implementasi dalam @capgo/capacitor-native-market, dan Menggunakan @capgo/capacitor-native-market untuk kemampuan asli dalam Menggunakan @capgo/capacitor-native-market.