Getting Started

1. Die Paketinstallation durchführen

   bun add @capgo/native-purchases

2. Synchronisieren mit native Projekten

   bunx cap sync

3. Kostenüberblick 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. Einkaufs- 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' zu purchaseProduct(). Siehe iOS-Monatsverpflichtungsabrechnungspläne für den vollständigen Fluss.

   iOS
   • In-App-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
   • In-App-Produkte und -Abonnements in Google Play Console erstellen.
     
   • Laden Sie mindestens eine interne Testversion hoch und fügen Sie Lizenz-Tester hinzu.
     
   • Fügen Sie die Abrechnungs-Erlaubnis zu 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	SKU/Produkt-ID konfiguriert in App Store Connect / Google Play Console.
productType	Nur Android	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBS. Standardmäßig INAPP. Immer auf SUBS für Abonnements.
planIdentifier	Android-Abonnements	Base-Plan-ID aus dem Google Play Console. Erforderlich für Abonnements, wird bei iOS- und In-App-Käufen ignoriert.
billingPlanType	IOS-Abonnements	StoreKit-Billing-Plan zum Kauf. Verwenden Sie dies 'monthly' zum monatlichen Abrechnungsmodell mit einer 12-monatigen Verpflichtung, wenn product.pricingTerms das Optionen offenlegt.
quantity	IOS	Nur für In-App-Käufe, standardmäßig 1. Android kauft immer ein Produkt.
appAccountToken	IOS + Android	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.
isConsumable	Android	Auf "Auto-Konsum" setzen, nachdem eine Berechtigung für Verbrauchsgüter gewährt wurde. Standardmäßig ist dies auf true Zustand überprüfen false.

Abschnitt mit dem Titel „Zustand überprüfen“

für eine plattformübergreifende Ansicht aller Transaktionen, die die Stores melden: getPurchases() In die Zwischenablage kopieren

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

Abschnitt mit dem Titel „Plattformverhalten“

• : Abonnements umfassen, und StoreKit 2-Hinweisunterstützung. In-App-Käufe erfordern Server-Belegvalidierung. isActive, expirationDate, willCancelEntitlements for consumables are checked on the client-side.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie die Google Play Developer API mit der purchaseToken für den autoritativen Status. purchaseState müssen PURCHASED und isAcknowledged müssen true.

API Schnellreferenz

• isBillingSupported() – Überprüfen Sie die Verfügbarkeit von StoreKit / Google Play.
• getProduct() / getProducts() – Laden Sie den Preis, den lokalisierten Titel, die Beschreibung, die Einführungsangebote und die unterstützten iOS-Preisbegriffe herunter.
• purchaseProduct() – Starten Sie den Kauffluss von StoreKit 2 oder Billing-Klient, einschließlich iOS-Monatsverpflichtungsabrechnungsplänen.
• restorePurchases() – Wiedergeben Sie historische Kaufvorgänge und synchronisieren Sie sie mit dem aktuellen Gerät.
• getPurchases() – alle iOS-Transaktionen oder Play Billing-Käufe auflisten.
• manageSubscriptions() – das native Abonnement-Verwaltung-UI öffnen.
• addListener('transactionUpdated') – bei App-Start (nur iOS) auf warten Sie auf StoreKit 2-Termine reagieren.

Gute 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 Käufe mit Konten zu verbinden.
3. Validieren Sie serverseitig – senden receipt (iOS) / purchaseToken (Android) an Ihren Backend für die Überprüfung.
4. Feine Fehler behandeln – überprüfen Sie die Benutzerstornierungen, Netzwerkfehler und nicht unterstützte Zahlungsumgebungen.
5. Gründlich testen – folgen Sie dem iOS Sandbox Guide und Android Sandbox Guide.
6. Wiederherstellung und Verwaltung anbieten – fügen Sie UI-Schaltflächen hinzu, die an die restorePurchases() Eine manageSubscriptions().

Ertrags-Schritte

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

Problembehandlung

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 während des Flusses abbrechen; umrunden Sie Anrufe mit try/catch und Oberflächen freundliche Fehlermeldungen.
• Für Android stellen Sie sicher, dass Testkonten die App vom 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 Abonnementzustand

• Verwenden Sie getPurchases() um den Laden mit Ihrem lokalen Berechtigungscache zu vergleichen.
• Auf Android fragen Sie immer den Google Play Developer API mit dem purchaseToken ab, um die Ablaufdaten oder den Rückgabestatus zu erhalten.
• Auf iOS überprüfen Sie isActive/expirationDate und überprüfen Sie die Quittungen, um Rückerstattungen oder Widerrufe zu erkennen.

Bleib weiter bei Getting Started

Wenn Sie Getting Started für die Planung der Genehmigung im App Store und der Verteilung verwenden, verbinden Sie es mit Mit @capgo/native-purchases für die native Fähigkeit in Mit @capgo/native-purchases, @capgo/capacitor-in-app-review für die Implementierungsdetails in @capgo/capacitor-in-app-review, Mit @capgo/capacitor-in-app-review für die native Fähigkeit in Mit @capgo/capacitor-in-app-review, @capgo/capacitor-native-market für die Implementierungsdetails in @capgo/capacitor-native-market, und Mit @capgo/capacitor-native-market für die native Fähigkeit in Mit @capgo/capacitor-native-market.