Getting Started

Copy sebuah prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/native-purchases`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-purchases/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Jendela terminal
Copy ke clipboard
```
bun add @capgo/native-purchases
```
Sinkron dengan proyek native
Jendela terminal
```
bunx cap sync
```

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

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

Implementasikan alur pembelian & 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();
```
Jika langganan iOS yang didukung kembali pricingTerms Anda dapat menampilkan opsi pembayaran bulanan dengan komitmen 12 bulan dan pass billingPlanType: 'monthly' ke purchaseProduct(). Lihat rencana pembayaran bulanan komitmen iOS untuk alur lengkap. iOS
- Android
- 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.
- Buat produk dalam aplikasi dan langganan di Google Play Console.
- Unggah setidaknya sebuah build uji internal dan tambahkan tester lisensi.
- iOS monthly commitment billing plans
- 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,
      }),
    });
  }
}

Pilihan pembelian yang diperlukan

Pilihan	Platform	Deskripsi
`productIdentifier`	iOS + Android	SKU/Kode Produk yang dikonfigurasi di App Store Connect / Google Play Console.
`productType`	Hanya untuk Android	`PURCHASE_TYPE.INAPP` atau `PURCHASE_TYPE.SUBS`. Defaultnya adalah `INAPP`. Selalu ditetapkan menjadi `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 membeli. Gunakan `'monthly'` untuk pembayaran bulanan dengan komitmen 12 bulan ketika `product.pricingTerms` menampilkan opsi tersebut.
`quantity`	__CAPGO_KEEP_0__	Hanya untuk pembelian dalam aplikasi, default ke `1`. Android selalu membeli satu item.
`appAccountToken`	iOS + Android	UUID/teks yang terkait dengan pembelian pengguna Anda. Diperlukan untuk UUID pada iOS; Android menerima string yang diobfuscasi hingga 64 karakter.
`isConsumable`	Android	Atur 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:

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

Sikap Platform

iOS: Langganan termasuk isActive, expirationDate, willCancel, dan dukungan penggunaan aplikasi StoreKit 2.
Pembelian dalam aplikasi memerlukan validasi bukti penerimaan server.: isActive/expirationDate are not populated; call the Google Play Developer API with the purchaseToken tidak diisi; hubungi pengembang Google Play Developer __CAPGO_KEEP_0__ untuk memeriksa status otoritatif. purchaseState harus diisi PURCHASED dan isAcknowledged harus diisi true.

API referensi cepat

isBillingSupported() – Periksa ketersediaan StoreKit / Google Play.
getProduct() / getProducts() – Ambil harga, judul lokal, 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 sinkronkan 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

Tampilkan harga toko – Apple memerlukan menampilkan harga product.title dan product.priceString; tidak pernah mengkodekan secara manual.
Gunakan appAccountToken – menghasilkan UUID (v5) secara deterministik dari ID pengguna untuk menghubungkan pembelian ke akun.
Validasi di server – kirim receipt (iOS) / purchaseToken (Android) ke backend Anda untuk verifikasi.
Tangani kesalahan dengan sopan – periksa pembatalan pengguna, gagal jaringan, dan lingkungan pembayaran yang tidak didukung.
Uji secara menyeluruh – ikuti Petunjuk Panduan Sandbox iOS dan Petunjuk Panduan Sandbox Android.
Tawar Kembalikan & Pengelolaan – tambahkan tombol UI yang terhubung ke restorePurchases() dan manageSubscriptions().

Langkah-Langkah Pendapatan Berikutnya

Setelah alur pembelian berfungsi, gunakan Revenue Playbook untuk merencanakan funnel pembayaran pertama Anda: skop produk, ASO, harga, penempatan paywall, analisis, dan umpan balik keluar

Pengaturan

Produk tidak dimuat

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.

Keadaan langganan tidak benar

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

Lanjutkan dari Getting Started

Getting Started untuk merencanakan persetujuan toko dan distribusi, hubungkan dengan Menggunakan @__CAPGO_KEEP_0__/native-purchases untuk kemampuan native di Menggunakan @capgo/native-purchases, for the native capability in Using @capgo/native-purchases, @capgo/capacitor-in-app-review for the implementation detail in @capgo/capacitor-in-app-review, Using @capgo/capacitor-in-app-review for the native capability in Using @capgo/capacitor-in-app-review, @capgo/capacitor-native-market for the implementation detail in @capgo/capacitor-native-market, and Using @capgo/capacitor-native-market for the native capability in Using @capgo/capacitor-native-market.