Inizia a utilizzare

Installazione

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

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

Infine utilizza il seguente prompt:

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. Installare il pacchetto

   bun add @capgo/native-purchases

2. Sincronizza con i progetti nativi

   bunx cap sync

3. Verifica il supporto 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 pricingTerms, puoi mostrare un'opzione di fatturazione mensile con un impegno di 12 mesi e passa billingPlanType: 'monthly' a purchaseProduct(). Vedi Piani di fatturazione mensile per iOS per il flusso completo.

   iOS
   • Crea prodotti e sottoscrizioni in-app in App Store Connect.
     
   • Utilizza StoreKit Local Testing o Sandbox testers per le prove di qualità.
     
   • Assicurati che i tuoi prodotti siano approvati. Nessuna modifica del manifesto è richiesta.
   Android
   • Crea prodotti e sottoscrizioni in-app in Google Play Console.
     
   • Carica almeno un build di test interno e aggiungi i testatori di 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	Codice SKU/ID prodotto configurato in App Store Connect / Google Play Console.
productType	Solo Android	PURCHASE_TYPE.INAPP o PURCHASE_TYPE.SUBS. Predefinito a INAPP. Sempre impostato a SUBS per le sottoscrizioni.
planIdentifier	Sottoscrizioni Android	ID Piano Base da Google Play Console. Richiesto per le sottoscrizioni, ignorato su iOS e per acquisti in-app.
billingPlanType	Sottoscrizioni 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 acquisti in-app, predefinito a 1. L'Android acquista sempre un oggetto.
appAccountToken	iOS + Android	ID UUID/insieme di caratteri che collega l'acquisto al tuo utente. Richiesto essere UUID su iOS; L'Android accetta qualsiasi stringa obfuscata fino a 64 caratteri.
isConsumable	Android	Impostato su true per consumare automaticamente i token dopo aver concesso l'entitatività per i consumabili. Predefinito a false.

Verifica stato di abbonamento

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 dispositivo

• iOS: Gli abbonamenti includono isActive, expirationDate, willCancele supporto per ascoltatore 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 ottenere lo status di autorità. purchaseState deve essere PURCHASED e isAcknowledged deve essere true.

API riferimento rapido

• 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 di Billing, incluso i piani mensili di fatturazione iOS.
• restorePurchases() – riproduci le acquisti storici e sincronizza con il dispositivo corrente.
• getPurchases() – elenca tutte le transazioni iOS o le acquisti di Play Billing.
• manageSubscriptions() – apri l'interfaccia utente di gestione delle sottoscrizioni nativa.
• addListener('transactionUpdated') – gestisci le transazioni StoreKit 2 pendenti quando il tuo app si avvia (solo iOS).

Pratiche raccomandate

1. Mostra il prezzo della store – Apple richiede di visualizzare product.title e product.priceString; non utilizzare mai la programmazione rigida.
2. Utilizza appAccountToken – generare deterministicamente un UUID (v5) dal ID dell'utente per collegare le acquisizioni agli account.
3. Valida server-side – invia receipt (iOS) / purchaseToken (Android) al tuo backend per la verifica.
4. Gestisci gli errori con delicatezza – controlla le cancellazioni degli utenti, le fallite connessioni di rete e gli ambienti di fatturazione non supportati.
5. Testa con attenzione – segui le guide del sandbox per iOS e Android Offri la gestione del restore e della fatturazione.
6. – aggiungi pulsanti di interfaccia utente collegati a e restorePurchases() passaggi successivi per la fatturazione del reddito. manageSubscriptions().

Handle errors gracefully is not translated as it is a protected token

Dopo che il flusso di acquisto funziona, utilizza il Revenue Playbook per pianificare il primo canale di entrate a pagamento: ambito del prodotto, ottimizzazione della visibilità negli store, prezzo, posizionamento del paywall, analisi e feedback sulla perdita di clienti.

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).
• Aspetta alcuni ore dopo aver creato i prodotti; la propagazione dello store non è istantanea.

Acquisto annullato o bloccato

• Gli utenti possono annullare il flusso a metà; avvolgi le chiamate in try/catch e messaggi di errore amichevoli per la superficie.
• Per Android, assicurati che gli account di test installino l'applicazione dallo Store di Gioco (pista interna) per far funzionare la fatturazione.
• Controlla logcat/Xcode per gli errori di fatturazione quando si esegue su dispositivo.

Lo stato della sottoscrizione è errato

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

Continua da Getting Started

Se stai utilizzando Inizia per pianificare l'approvazione e la distribuzione del negozio, connettilo con Utilizza @capgo/native-purchases per la capacità nativa in Utilizza @capgo/native-purchases, @capgo/capacitor-in-app-review per la dettagliata implementazione in @capgo/capacitor-in-app-review, Utilizza @capgo/capacitor-in-app-review per la capacità nativa in Utilizza @capgo/capacitor-in-app-review, @capgo/capacitor-native-market per la dettagliata implementazione in @capgo/capacitor-native-market, e Utilizza @capgo/capacitor-native-market per la capacità nativa in Utilizzare @capgo/capacitor-native-market.