Erste Schritte

Installation

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

1. Paket installieren

   bun add @capgo/native-purchases

2. Mit nativen Projekten synchronisieren

   bunx cap sync

3. Billing-Support prüfen

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

4. Produkte direkt aus den Stores laden

   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. Purchase- & Restore-Flows 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();

   Monatliche Commitment-Pläne für iOS

   Wenn ein unterstütztes iOS-Abonnement zurückgibt pricingTerms, können Sie eine monatliche Abrechnungsoption mit 12-Monats-Commitment anzeigen und übergeben billingPlanType: 'monthly' zu purchaseProduct(). Siehe Monatliche Commitment-Abrechnungspläne für iOS für den gesamten Ablauf.

   iOS
   • Erstelle In-App-Produkte und Abonnements in App Store Connect.
     
   • Nutze StoreKit Local Testing oder Sandbox-Tester für QA.
     
   • Keine Manifest-Änderungen erforderlich. Stelle sicher, dass deine Produkte freigegeben sind.
   Android
   • Erstelle In-App-Produkte und Abonnements in der Google Play Console.
     
   • Lade mindestens einen internen Test-Build hoch und füge Lizenz-Tester hinzu.
     
   • Füge die Billing-Berechtigung zu AndroidManifest.xml:

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

Beispiel für Purchase-Service

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	In App Store Connect / Google Play Console konfigurierte SKU/Produkt-ID.
productType	Nur Android	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBS. Standardmäßig INAPP. Immer gesetzt auf SUBS für Abonnements.
planIdentifier	Android-Abonnements	Base Plan ID aus der Google Play Console. Erforderlich für Abonnements, wird bei iOS und In-App-Käufen ignoriert.
billingPlanType	iOS-Abonnements	StoreKit-Abrechnungsplan zum Kauf. Nutze 'monthly' für monatliche Abrechnung mit 12-Monats-Verpflichtung, wenn product.pricingTerms diese Option bereitstellt.
quantity	iOS	Nur für In-App-Käufe, Standardwert ist 1. Android kauft immer nur ein Element.
appAccountToken	iOS + Android	UUID/String, der den Kauf mit Ihrem Benutzer verknüpft. Auf iOS ist eine UUID erforderlich; Android akzeptiert jeden obfuskierten String bis zu 64 Zeichen.
isConsumable	Android	Auf true um Tokens nach der Berechtigungsvergabe für Verbrauchsgüter automatisch zu verbrauchen. Standardmäßig false.

Entitlement-Status prüfen

Nutzt getPurchases() für eine plattformübergreifende Übersicht aller von den Stores gemeldeten Transaktionen:

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 beinhalten isActive, expirationDate, willCancel, sowie StoreKit 2 Listener-Support. In-App-Käufe erfordern eine serverseitige Belegvalidierung.
• Android: isActive/expirationDate sind nicht befüllt; rufen Sie die Google Play Developer API mit dem purchaseToken für den verbindlichen Status auf. purchaseState muss PURCHASED und isAcknowledged muss true.

API Kurzübersicht

• isBillingSupported() – Verfügbarkeit von StoreKit / Google Play prüfen.
• getProduct() / getProducts() – Preis, lokalisierten Titel, Beschreibung, Intro-Angebote und unterstützte iOS-Preisbedingungen abrufen.
• purchaseProduct() – Kaufablauf über StoreKit 2 oder Billing-Client starten, einschließlich monatlicher Abonnementpläne für iOS.
• restorePurchases() – frühere Käufe wiederherstellen und mit dem aktuellen Gerät synchronisieren.
• getPurchases() – alle iOS-Transaktionen oder Play-Billing-Käufe auflisten.
• manageSubscriptions() – die native Abonnement-Verwaltungsoberfläche öffnen.
• addListener('transactionUpdated') – ausstehende StoreKit 2-Transaktionen beim App-Start verarbeiten (nur iOS).

Best Practices

1. Store-Preise anzeigen – Apple verlangt die Anzeige von product.title und product.priceString; niemals hartkodieren.
2. Nutzt appAccountToken – einen UUID (v5) deterministisch aus der Benutzer-ID generieren, um Käufe mit Konten zu verknüpfen.
3. Serverseitig validieren – senden receipt (iOS) / purchaseToken (Android) zur Verifizierung an dein Backend.
4. Fehler sauber behandeln – Prüfe auf Nutzerabbrüche, Netzwerkfehler und nicht unterstützte Abrechnungsumgebungen.
5. Gründlich testen – folge dem iOS-Sandbox-Guide und Android-Sandbox-Guide.
6. Restore & Verwaltung anbieten – füge UI-Buttons hinzu, die an restorePurchases() und manageSubscriptions().

Nächste Schritte mit Revenue

Sobald der Kaufprozess funktioniert, nutze den Umsatz-Playbook Um deinen ersten Paid Funnel zu planen: Produktumfang, ASO, Pricing, Paywall-Platzierung, Analytics und Churn-Feedback.

Fehlerbehebung

Produkte werden nicht geladen

• Stelle sicher, dass die Bundle ID / Application ID mit der Store-Konfiguration übereinstimmt.
• Prüfe, ob die Product IDs aktiv und freigegeben (App Store) oder aktiviert (Google Play) sind.
• Warte nach dem Anlegen der Produkte einige Stunden; die Stores übernehmen sie nicht sofort.

Kauf abgebrochen oder hängt

• User können den Flow abbrechen; umschließe die Aufrufe mit try/catch und zeige benutzerfreundliche Fehlermeldungen an.
• Bei Android müssen Test-Accounts die App über den Play Store (interner Test-Track) installieren, damit Billing funktioniert.
• Prüfe logcat/Xcode auf Abrechnungsfehler, wenn die App auf dem Gerät läuft.

Abonnementstatus inkorrekt

• Nutzt getPurchases() um Store-Daten mit deinem lokalen Entitlement-Cache zu vergleichen.
• Auf Android immer die Google Play Developer API mit dem purchaseToken abfragen, um Ablaufdaten oder Erstattungsstatus zu erhalten.
• Auf iOS prüfen isActive/expirationDate und Receipts validieren, um Erstattungen oder Widerrufe zu erkennen.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Store-Zulassung und Distribution zu planen, verknüpfen Sie es mit @capgo/native-purchases verwenden für die native Funktionalität bei der Nutzung von @capgo/native-purchases, @capgo/capacitor-in-app-review für die Implementierungsdetails in @capgo/capacitor-in-app-review, @capgo/capacitor-in-app-review nutzen für die native Funktion bei der Nutzung von @capgo/capacitor-in-app-review, @capgo/capacitor-native-market für das Implementierungsdetail in @capgo/capacitor-native-market, und @capgo/capacitor-native-market nutzen für die native Funktionalität bei der Nutzung von @capgo/capacitor-native-market.