Inizia

Istallazione

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo competenze al tuo strumento di AI utilizzando il seguente comando:

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

Poi utilizza la seguente richiesta:

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

Se preferisci l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

1. Installa il pacchetto

   bun add @capgo/native-purchases

2. Sincronizza con i progetti nativi

   bunx cap sync

3. Verifica il supporto alla fatturazione

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

4. Carica i prodotti direttamente dai negozi

   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. Implementa flussi di acquisto e di ripristino

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

   Piani di impegno mensile per iOS

   Se un abbonamento iOS supportato restituisce pricingTermspuoi mostrare un'opzione di fatturazione mensile con un impegno di 12 mesi e passare billingPlanType: 'monthly' a purchaseProduct(). Vedi Piani di fatturazione mensile per iOS per il flusso completo.

   IOS
   • Creare prodotti e abbonamenti in-app in App Store Connect.
     
   • Usare StoreKit Local Testing o Sandbox tester per le prove di qualità.
     
   • Non sono necessarie modifiche al manifesto. Assicurati che i tuoi prodotti siano approvati.
   Android
   • Creare prodotti e abbonamenti in-app in Google Play Console.
     
   • Carica almeno una versione di test interna e aggiungi i tester della licenza.
     
   • Aggiungi la permessione di fatturazione a AndroidManifest.xml:

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

Esempio di servizio di acquisto

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

Opzioni di acquisto richieste

Opzione	Piattaforma	Descrizione
productIdentifier	iOS + Android	ID SKU/ID prodotto configurato in App Store Connect / Google Play Console.
productType	Solo per Android	PURCHASE_TYPE.INAPP o PURCHASE_TYPE.SUBSo INAPPper le sottoscrizioni. SUBS Sottoscrizioni per Android
planIdentifier	ID Piano Base da Google Play Console. Richiesto per le sottoscrizioni, ignorato su iOS e per le acquisti in-app.	per le sottoscrizioni.
billingPlanType	Abbonamenti iOS	Piano di fatturazione StoreKit per l'acquisto. Utilizza 'monthly' per la fatturazione mensile con un impegno di 12 mesi quando product.pricingTerms esporre quella opzione.
quantity	IOS	Solo per gli acquisti in-app, predefinito a 1. L'Android acquista sempre un oggetto.
appAccountToken	IOS + Android	Solo per iOS e Android
isConsumable	ID UUID/ stringa che collega l'acquisto al tuo utente. Richiesto che sia UUID su iOS; l'Android accetta qualsiasi stringa obfuscatrice fino a 64 caratteri.	Android true Impostato su false.

Verifica lo stato dell'entità

Usa getPurchases() per una vista cross-platform di ogni transazione che i negozi segnalano:

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

Comportamento del sistema

• iOS: Le sottoscrizioni includono isActive, expirationDate, willCancel, e supporto per l'ascolto di StoreKit 2. Le vendite in-app richiedono la validazione del ricevuto server.
• Android: isActive/expirationDate non sono popolate; chiama il Google Play Developer API con il purchaseToken per status di autorità. purchaseState deve essere PURCHASED e isAcknowledged deve essere true.

API quick reference

• isBillingSupported() – controlla la disponibilità di StoreKit / Google Play.
• getProduct() / getProducts() – recupera il prezzo, titolo localizzato, descrizione, offerte introduttive e termini di prezzo iOS supportati.
• purchaseProduct() – avvia il flusso di acquisto del client di StoreKit 2 o Billing, incluso i piani mensili di fatturazione iOS.
• restorePurchases() – riproduca le transazioni storiche e sincronizza con il dispositivo corrente.
• getPurchases() – elenca tutte le transazioni iOS o le compravendite di Play Billing.
• manageSubscriptions() – apre l'interfaccia utente di gestione delle sottoscrizioni native.
• addListener('transactionUpdated') – gestisci le transazioni StoreKit 2 in attesa quando il tuo app si avvia (solo iOS).

Prassi ottimali

1. Mostra prezzi della store – Apple richiede di visualizzare product.title e product.priceStringnon hardcoded.
2. Usa appAccountToken – generare deterministicamente un UUID (v5) dal tuo ID utente per collegare le acquisti ai conti.
3. Valuta server-side – invia receipt (iOS) / purchaseToken Verifica (Android) con il tuo backend per la verifica.
4. Tratta gli errori con delicatezza. – controlla le cancellazioni dell'utente, le fallite di rete e gli ambienti di fatturazione non supportati.
5. Testa accuratamente. – segui le istruzioni del guida del sandbox iOS e context: Pagina/Area: Sito web di marketing Capgo. Ruolo: Etichetta UI breve o elemento di navigazione. Visualizzato in: pagina trust.astro. Chiave messaggio `e` (E)..
6. guida del sandbox Android Offri la gestione del ripristino e della fatturazione restorePurchases() – aggiungi pulsanti di interfaccia utente collegati a manageSubscriptions().

e

Dopo che il flusso di acquisto funziona, utilizza il Revenue Playbook per pianificare il tuo primo canale di pagamento: ambito del prodotto, ottimizzazione della visibilità, prezzo, posizionamento della barriera di pagamento, analisi e feedback sulla churn.

Risoluzione dei problemi

Prodotti non caricati

• Assicurati che l'ID del bundle / ID dell'applicazione corrisponda alla configurazione dello store.
• Conferma che gli ID dei prodotti sono attivi e approvati (App Store) o attivati (Google Play).
• Attendi alcuni ore dopo aver creato i prodotti; la propagazione dello store non è istantanea.

Acquisto annullato o bloccato

• Gli utenti possono annullare durante il flusso; avvolgi le chiamate in try/catch e messaggi di errore amichevoli per l'utente.
• Per Android, assicurati che gli account di test installino l'applicazione dal Play Store (track interno) affinché la fatturazione funzioni.
• Controlla logcat/Xcode per gli errori di fatturazione quando si esegue l'applicazione sul dispositivo.

Lo stato della sottoscrizione è errato.

• Usa getPurchases() per confrontare i dati dello store con il cache delle tue autorizzazioni locali.
• Sul dispositivo Android, consulta sempre il Google Play Developer API con il purchaseToken per ottenere le date di scadenza o lo stato di rimborso.
• Sul dispositivo iOS, controlla isActive/expirationDate e validare le ricevute per rilevare i rimborsi o le revocazioni.

Continua da qui dal Getting Started

If sei stai utilizzando Avvio rapido per pianificare l'approvazione della store e la distribuzione, connettilo con Utilizzare @capgo/acquisti nativi per la capacità nativa in Utilizzare @capgo/acquisti nativi, @capgo/capacitor-recensione in-app per il dettaglio di implementazione in @capgo/capacitor-recensione in-app, Utilizzare @capgo/capacitor-recensione in-app per la capacità nativa in Utilizzare @capgo/capacitor-recensione in-app, @capgo/capacitor-mercato nativo per il dettaglio di implementazione in @capgo/capacitor-mercato nativo, e Utilizzare @capgo/capacitor-mercato nativo per la capacità nativa in Using @capgo/capacitor-native-market.