Mulai

Pemasangan

Anda dapat menggunakan Pengaturan Bantu AI untuk memasang plugin. Tambahkan kemampuan Capgo 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, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

1. Instal paket

   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. Implement 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();

   Rencana komitmen bulanan iOS

   Jika langganan iOS yang didukung kembali pricingTerms, Anda dapat menampilkan opsi pembayaran bulanan dengan komitmen 12 bulan dan mengirimkan billingPlanType: 'monthly' ke purchaseProduct(). Lihat Rencana pembayaran bulanan komitmen iOS untuk alur penuh.

   iOS
   • Buat produk dalam aplikasi dan langganan di App Store Connect.
     
   • Menggunakan StoreKit Local Testing atau Sandbox tester untuk QA.
     
   • Tidak perlu mengedit manifest. Pastikan produk Anda disetujui.
   Android
   • Buat produk dalam aplikasi dan langganan di Google Play Console.
     
   • Unggah setidaknya satu versi uji internal dan tambahkan tester lisensi.
     
   • Tambahkan izin billing 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	Kode SKU/ID Produk yang telah dikonfigurasi di App Store Connect / Google Play Console.
productType	Hanya untuk Android	PURCHASE_TYPE.INAPP atau PURCHASE_TYPE.SUBSatau INAPPuntuk langganan. SUBS Langganan Android
planIdentifier	ID Plan Dasar dari Google Play Console. Diperlukan untuk langganan, diabaikan pada iOS dan pembelian dalam aplikasi.	untuk langganan.
billingPlanType	Langganan iOS	Rencana tagihan StoreKit untuk pembelian. Gunakan 'monthly' untuk tagihan bulanan dengan komitmen 12 bulan ketika product.pricingTerms mengungkapkan opsi tersebut.
quantity	iOS	Hanya untuk pembelian dalam aplikasi, default ke 1. Android selalu membeli satu item.
appAccountToken	iOS + Android	context: Halaman/Bidang: Halaman pembangun Capgo / produk halaman bangun awan native. Peran: Label UI pendek atau item navigasi. Kunci pesan `native_build_builder_stat_platforms_value` (Nilai Statik Platform Pembangun Native Build). | Halaman/Bidang: Halaman pemasaran solusi Capgo. Peran: Label UI pendek atau item navigasi. Kunci pesan `solutions_lovable_to_mobile_stat2_value` (Nilai Stat2 Solusi Lovable To Mobile). | Halaman/Bidang: Halaman pemasaran solusi Capgo. Peran: Label UI pendek atau item navigasi. Kunci pesan `solutions_webapp_to_mobile_stat2_value` (Nilai Stat2 Solusi Webapp To Mobile).
isConsumable	UUID/teks yang menghubungkan pembelian ke pengguna Anda. Diperlukan untuk UUID di iOS; Android menerima teks yang diobfuskan hingga 64 karakter.	Android true Ditetapkan ke false.

Memeriksa status hak akses

Pilih untuk melihat tampilan lintas platform dari setiap transaksi yang toko laporan: getPurchases() Salin ke papan klip

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

Judul Bagian “Perilaku Platform”

• : Langganan termasuk, dan dukungan pemantauan StoreKit 2. Pembelian dalam aplikasi memerlukan validasi bukti server. isActive, expirationDate, willCancelAndroid
• tidak diisi; panggil Google Play Developer __CAPGO_KEEP_0__ dengan: isActive/expirationDate API purchaseToken untuk status otoritatif. purchaseState harus ada PURCHASED dan isAcknowledged context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan). true.

API quick reference

• isBillingSupported() Judul bagian “__CAPGO_KEEP_0__ referensi cepat”
• getProduct() / getProducts() – periksa ketersediaan StoreKit / Google Play.
• purchaseProduct() – ambil harga, judul lokal, deskripsi, tawaran intro, dan istilah harga iOS yang didukung.
• restorePurchases() – mulai alur pembelian StoreKit 2 atau Billing klien, termasuk rencana pembayaran bulanan iOS.
• getPurchases() – ulangi pembelian sejarah dan sinkron ke perangkat saat ini.
• manageSubscriptions() – daftar semua transaksi iOS atau pembelian Billing Play.
• addListener('transactionUpdated') – mengatasi transaksi StoreKit 2 yang menunggu ketika aplikasi Anda dimulai (hanya untuk iOS).

Praktik terbaik

1. Tampilkan harga toko – Apple memerlukan menampilkan product.title dan product.priceString; tidak pernah mengkodekan secara keras.
2. Pilih appAccountToken – menghasilkan UUID secara deterministik (v5) dari ID pengguna Anda untuk menghubungkan pembelian ke akun.
3. Validasi di server – kirim receipt (iOS) / purchaseToken Verifikasi dengan (Android) ke backend Anda.
4. Tangani kesalahan dengan sopan. – Periksa pembatalan pengguna, kegagalan jaringan, dan lingkungan pembayaran yang tidak didukung.
5. Uji secara menyeluruh. – Ikuti panduan sandbox dan Panduan sandbox iOS. dan.
6. Panduan sandbox Android. Tawarkan pengembalian dan pengelolaan. restorePurchases() – Tambahkan tombol UI yang terhubung ke manageSubscriptions().

Tahap selanjutnya untuk pendapatan.

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

Penyelesaian Masalah

Judul Bagian: “Penyelesaian Masalah”

• Produk Tidak Terisi
• Pastikan ID Paket / 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 try/catch dan pesan kesalahan yang ramah pengguna.
• Untuk Android, pastikan akun uji instal aplikasi dari Play Store (track internal) sehingga Billing berfungsi.
• Cek logcat/Xcode untuk kesalahan billing ketika menjalankan di perangkat.

Keadaan langganan salah

• Pilih 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 tagihan untuk mendeteksi pengembalian uang atau pembatalan.

Teruskan dari Getting Started

If Anda menggunakan Getting Started untuk merencanakan persetujuan toko dan distribusi, hubungkannya dengan Menggunakan @capgo/native-purchases untuk kemampuan native di 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 kemampuan native di 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 kemampuan asli di Menggunakan @capgo/capacitor-native-market.