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

Installation

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 den native Projekten

   bunx cap sync

3. Überprüfen Sie die Abrechnungsunterstützung

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

   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 Abrechnungen hinzu AndroidManifest.xml:

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

Beispiel für 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	Produkt-ID / SKU im App Store Connect / Google Play Console
productType	nur Android	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBSoder INAPP. Standardmäßig SUBS . Immer auf
planIdentifier	zur Abonnement	Abonnements für Android-Geräte
billingPlanType	iOS-Abonnements	StoreKit-Billing-Plan zum Kauf verwenden. Nutzen Sie 'monthly' zum monatlichen Abrechnen mit einer 12-monatigen Verpflichtung, wenn product.pricingTerms exponiert, dass Option.
quantity	iOS	Nur für In-App-Käufe, standardmäßig 1. Android kauft immer ein Produkt.
appAccountToken	iOS + Android	Kontext: Seite/ Bereich: Capgo Builder / native Cloud-Build-Produktseite. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichtenschlüssel `native_build_builder_stat_platforms_value` (Native Build Builder Stat Platforms Value). | Seite/Bereich: Capgo-Lösungen-Marketingseite. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichtenschlüssel `solutions_lovable_to_mobile_stat2_value` (Solutions Lovable To Mobile Stat2 Value). | Seite/Bereich: Capgo-Lösungen-Marketingseite. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichtenschlüssel `solutions_webapp_to_mobile_stat2_value` (Solutions Webapp To Mobile Stat2 Value).
isConsumable	UUID/Zeichenfolge, 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 Stores 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 StoreKit 2-Hinweisgebersupport. In-App-Käufe erfordern eine Server-Belegvalidierung.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie die Google Play-Entwickler-API mit der purchaseToken für autoritatives 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() – Abrufen Sie den Preis, die lokalisierte Überschrift, Beschreibung, Einführungsangebote und unterstützte iOS-Preistypen.
• purchaseProduct() – Initiieren 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 Abonnementverwaltungsoberfläche.
• addListener('transactionUpdated') – beim Start Ihrer App (nur iOS) ausstehende StoreKit 2-Transaktionen verarbeiten.

Beste Praktiken

1. Preise im App Store 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 – überprüfen Sie die Benutzerkancellierung, Netzwerkfehler und nicht unterstützte Zahlungsmechanismen.
4. Testen Sie gründlich. – folgen Sie der
5. iOS Sandbox-Leitfaden und – überprüfen Sie die Benutzerkancellierung, Netzwerkfehler und nicht unterstützte Zahlungsmechanismen. Testen Sie gründlich. – folgen Sie der .
6. Android Sandbox-Leitfaden Angebot von Wiederherstellung und Verwaltung restorePurchases() – fügen Sie UI-Schaltflächen hinzu, die mit manageSubscriptions().

und

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

Fehlerbehebung

Produkte laden nicht

• Stellen Sie sicher, dass die Bundle-ID / Anwendungs-ID der Store-Konfiguration 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 Store-Verbreitung ist nicht sofort.

Kauf wurde abgebrochen oder hängt

• Benutzer können mitten im Fluss abbrechen; Aufrufe in try/catch und freundliche Fehlermeldungen für die Oberfläche.
• Für Android stellen Sie sicher, dass Testkonten die App aus dem Google Play Store (internes Track) installieren, damit Billing funktioniert.
• Überprüfen Sie logcat/Xcode für Fehler bei der Abrechnung, wenn Sie auf einem Gerät laufen.

Ungültiger Abonnementzustand

• Verwenden Sie getPurchases() um die Daten des Stores 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 die Eingaberechnungen, um Rückzahlungen oder Widerrufe zu erkennen.

Fortsetzen von Getting Started

Wenn Sie es verwenden Einstieg um die Genehmigung und Verteilung im App Store zu planen, verbinden Sie es mit Verwenden Sie @capgo/native-purchases für die native Fähigkeit in Verwenden Sie @capgo/native-purchases für die Implementierungsdetails in @capgo/capacitor-in-app-review Verwenden Sie @capgo/capacitor-in-app-review für die native Fähigkeit in Verwenden Sie @capgo/capacitor-in-app-review für die Implementierungsdetails in @capgo/capacitor-native-market und Verwenden Sie @capgo/capacitor-native-market für die native Fähigkeit in Verwenden Sie @capgo/capacitor-native-market für die Implementierungsdetails in @capgo/capacitor-native-market für die native Fähigkeit in Using @capgo/capacitor-native-market.