Getting Started

Abschnitt mit dem Titel „Installation“

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Installationsanleitung

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

Wenn Sie eine manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die unten angegebenen Plattform-spezifischen Anweisungen befolgen:

1. Installieren Sie das Paket

   bun add @capgo/native-purchases

2. Synchronisieren Sie sich mit native Projekten

   bunx cap sync

3. Überprüfen Sie die Unterstützung für Abrechnungen

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

4. Laden Sie Produkte direkt aus den Geschäften

   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. Kauf- und Wiederherstellungsflüsse implementieren

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

   iOS-Monatsverpflichtungspläne

   Wenn ein unterstützter iOS-Abonnement zurückgegeben wird pricingTerms, Sie können eine monatliche Abrechnungsoption mit einer 12-monatigen Verpflichtung anzeigen und billingPlanType: 'monthly' zum purchaseProduct()Siehe iOS-Monatsverpflichtungsabrechnungspläne für den vollständigen Fluss.

   iOS
   • Produkte und Abonnements in App Store Connect erstellen.
     
   • Verwenden Sie StoreKit Local Testing oder Sandbox-Tester für QA.
     
   • Keine Manifest-Änderungen erforderlich. Stellen Sie sicher, dass Ihre Produkte genehmigt sind.
   Android
   • Erstellen Sie Produkte und Abonnements in Google Play Console.
     
   • Laden Sie mindestens eine interne Testversion hoch und fügen Sie Lizenz-Tester hinzu.
     
   • Fügen Sie die Genehmigung für die Abrechnung hinzu AndroidManifest.xml:

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

Beispiel für den Kaufdienst

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

Erforderliche Kaufoptionen

Option	Plattform	Beschreibung
productIdentifier	iOS + Android	Artikelnummer/Konfigurierte Produkt-ID in App Store Connect / Google Play Console.
productType	Android nur	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBSoder INAPPoder SUBS oder
planIdentifier	. Standardmäßig	. Immer auf "(Subskriptionen)" gesetzt.
billingPlanType	iOS-Abonnements	StoreKit-Billigungsplan zum Kauf verwenden. Nutzen Sie 'monthly' zum monatlichen Abrechnen mit einer 12-monatigen Verpflichtung, wenn product.pricingTerms exponiert wird.
quantity	iOS	Nur für In-App-Käufe, standardmäßig 1. Android kauft immer ein Produkt.
appAccountToken	iOS + Android	iOS + Android
isConsumable	UUID/Zahl, die den Kauf mit Ihrem Benutzer verbindet. Erforderlich, um auf iOS eine UUID zu sein; Android akzeptiert jede verschlüsselte Zeichenfolge bis zu 64 Zeichen.	Android true Setzen Sie auf false.

Zugriffsstatus überprüfen

Verwenden getPurchases() für einen plattformübergreifenden Überblick über alle Transaktionen, die die Geschäftsplätze melden:

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

Plattformverhalten

• iOS: Abonnements umfassen isActive, expirationDate, willCancel, und Unterstützung für den StoreKit 2-Hörer. In-App-Käufe erfordern eine Server-Belege-Validierung.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie die Google Play-Entwickler-API API mit dem purchaseToken zum autorisierten Status. purchaseState muss sein PURCHASED und isAcknowledged muss sein true.

API Schnellreferenz

• isBillingSupported() – Überprüfen Sie die Verfügbarkeit von StoreKit / Google Play.
• getProduct() / getProducts() – Laden Sie den Preis, die lokalisierte Überschrift, Beschreibung, Einführungsangebote und unterstützte iOS-Preistypen herunter.
• purchaseProduct() – Starten Sie den Kauffluss von StoreKit 2 oder Billing-Klient, einschließlich iOS-Monatsverpflichtungsabrechnungsplänen.
• restorePurchases() – Wiederholen Sie historische Kaufvorgänge und synchronisieren Sie sie mit dem aktuellen Gerät.
• getPurchases() – Listen Sie alle iOS-Transaktionen oder Play-Billing-Käufe auf.
• manageSubscriptions() – Öffnen Sie die native Abonnement-Verwaltungsoberfläche.
• addListener('transactionUpdated') – verarbeiten Sie bei App-Start (nur iOS) ausstehende StoreKit 2-Tansaktionen.

Best Practices

1. Preise anzeigen – Apple erfordert die Anzeige von product.title und product.priceString; niemals festkodieren.
2. Verwenden Sie appAccountToken – generieren Sie deterministisch eine UUID (v5) aus Ihrem Benutzer-ID, um Kaufleistungen mit Konten zu verbinden.
3. Serverseitig überprüfen – senden Sie receipt (nur iOS) / purchaseToken (Android) zur Überprüfung an Ihren Backend senden.
4. Fehler sanft handhaben – Überprüfen Sie die Benutzerstornierung, Netzwerkfehler und nicht unterstützte Zahlungsumgebungen.
5. Sorgfältig testen – folgen Sie der iOS-Sandbox-Anleitung und Android-Sandbox-Anleitung.
6. Zahlungsergebnisse und Verwaltung anbieten – Hinzufügen Sie UI-Schaltflächen, die an restorePurchases() und manageSubscriptions().

Zahlungsergebnisse nachfolgende Schritte

Nachdem der Kauffluss funktioniert, verwenden Sie das Einnahmen-Handbuch um Ihren ersten bezahlten Kanal zu planen: Produktumfang, ASO, Preis, Paywall-Platzierung, Analytics und Rückschläge bei der Abmeldung.

Ereignisse

Stellen Sie sicher, dass die Bundle-ID / Anwendungs-ID der Lagerungskonfiguration entspricht.

• Bestätigen Sie, dass die Produkt-IDs aktiv und genehmigt (App Store) oder aktiviert (Google Play) sind.
• Warten Sie einige Stunden nach der Erstellung von Produkten; die Lagerung wird nicht sofort propagiert.
• Kauf abgebrochen oder hängen geblieben

Benutzer können mitten im Fluss abbrechen; umschließen Sie Aufrufe mit

• __CAPGO_KEEP_0__ try/catch und freundliche Fehlermeldungen.
• Für Android stellen Sie sicher, dass Testkonten die App aus dem Google Play Store (internes Track) installieren, damit die Abrechnung funktioniert.
• Überprüfen Sie logcat/Xcode für Abrechnungsfehler, wenn Sie auf einem Gerät laufen.

Falsche Zustand der Abonnement

• Verwenden Sie getPurchases() um die Daten des Ladens mit Ihrem lokalen Berechtigungscache zu vergleichen.
• Bei Android stellen Sie immer die Google Play Developer API mit der purchaseToken um die Ablaufdaten oder den Rückgabestatus zu erhalten.
• Bei iOS überprüfen Sie isActive/expirationDate und überprüfen Sie die Quittungen, um Rückzahlungen oder Widerrufe zu erkennen.

Fortsetzen Sie von Getting Started

If Sie Native-Einkäufe verwenden Anleitung zum Starten um die Genehmigung und Verteilung im App Store zu planen, verbinden Sie es mit Verwenden Sie @capgo/native-purchases zur Verwendung der native Fähigkeit in Verwenden Sie @capgo/native-purchases Verwenden Sie @capgo/capacitor-in-app-review zur Verwendung der native Fähigkeit in Verwenden Sie @capgo/capacitor-in-app-review Verwenden Sie @capgo/capacitor-in-app-review zur Verwendung der native Fähigkeit in Verwenden Sie @capgo/capacitor-in-app-review Verwenden Sie @capgo/capacitor-native-market zur Verwendung der native Fähigkeit in Verwenden Sie @capgo/capacitor-native-market Verwenden Sie @capgo/capacitor-native-market für die native Fähigkeit in @capgo/capacitor-native-market.