Getting Started

Installation

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Werkzeugleistung mit der folgenden Befehl hinzu:

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

Verwenden Sie dann die folgende Anfrage:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten aufgeführten plattformabhängigen Anweisungen:

1. Install das Paket

   bun add @capgo/native-purchases

2. Synchronisiere mit native Projekten

   bunx cap sync

3. Überprüfe die Rechnungssupport

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

4. Lade Produkte direkt aus den Stores

   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. Implementiere 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 monatliche Verpflichtungspläne

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

   iOS
   • Erstellen Sie in-App-Produkte und -Abonnements in App Store Connect.
     
   • 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 Lizenzprüfer hinzu.
     
   • Fügen Sie die Abrechnungsberechtigung zu 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/Produkt-ID in App Store Connect / Google Play Console konfiguriert.
productType	Nur Android	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBS. Standardmäßig ist INAPP. Immer auf SUBS für Abonnements.
planIdentifier	Android-Abonnements	Basierendes Produkt-ID von Google Play Console. Erforderlich für Abonnements, wird bei iOS und In-App-Käufen ignoriert.
billingPlanType	iOS-Abonnements	StoreKit-Abrechnungsplan zum Kauf. Verwenden 'monthly' für monatliche Abrechnung mit einer 12-monatigen Verpflichtung wenn product.pricingTerms enthüllt diese Option.
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	Setzen Sie auf true um Token automatisch nach der Berechtigung für Verbrauchsgüter zu konsumieren. Standardmäßig false.

Überprüfung der Berechtigungszustände

Verwenden getPurchases() für eine plattformübergreifende Ansicht aller Transaktionen, die die Geschäfte 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, willCancelund StoreKit 2-Hinweisunterstützung. In-App-Käufe erfordern eine Server-Belegevalidierung.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie die Google Play-Entwickler-API mit dem purchaseToken für eine autoritative Status. purchaseState müssen 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') – Behandeln Sie bei App-Start die laufenden StoreKit 2-Vorgänge (nur iOS).

Gute Praktiken

1. Preise im App Store anzeigen – Apple verlangt 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 Kaufe mit Konten zu verbinden.
3. Validieren Sie serverseitig – senden Sie receipt (iOS) / purchaseToken (Android) an Ihren Backend für die Verifizierung.
4. Fehler verträglich behandeln – Überprüfen Sie die Benutzerkündigung, Netzwerkfehler und nicht unterstützte Abrechnungsumgebungen.
5. Sorgfältig testen – folgen Sie der iOS Sandbox-Leitfaden und Android Sandbox-Leitfaden.
6. Angebot wiederherstellen und verwalten – fügen Sie UI-Schaltflächen hinzu, die an restorePurchases() und manageSubscriptions().

Einnahmen-Schritte

Nachdem der Kauffluss funktioniert, verwenden Sie das Einnahme-Handbuch Um Ihren ersten bezahlten Kanal zu planen: Produktumfang, ASO, Preisgestaltung, Paywall-Platzierung, Analytics und Rückschläufe bei der Abwanderung.

Problembehandlung

Produkte laden nicht

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

Kauf abgebrochen oder hängen geblieben

• Benutzer können mitten im Flow abbrechen; Wrap Aufrufe in try/catch und freundliche Fehlermeldungen an die Oberfläche bringen.
• Für Android stellen Sie sicher, dass Testkonten die App vom Play Store (internes Track) installieren, damit Billing funktioniert.
• Überprüfen Sie logcat/Xcode auf Rechnungsfehler, wenn Sie auf einem Gerät laufen.

Fehlerhaftes Abonnementzustand

• Verwenden Sie getPurchases() um den Laden von Daten mit Ihrem lokalen Berechtigungscache zu vergleichen.
• Bei Android wird immer die Google Play Developer API abgefragt, um purchaseToken zu erhalten oder den Status von Rückerstattungen.
• Bei iOS überprüfen Sie isActive/expirationDate und überprüfen Sie die Rechnungen, um Rückerstattungen oder Widerrufe zu erkennen.

Weiter von Getting Started

Wenn Sie Getting Started verwenden Getting Started um die Genehmigung und Verteilung im App Store zu planen und zu verbinden, verbinden Sie es mit Mit @capgo/native-purchases für die native Fähigkeit in Mit @capgo/native-purchases, @capgo/capacitor-in-app-Bewertung für die Implementierungsdetail in @capgo/capacitor-in-app-Bewertung, Mit @capgo/capacitor-in-app-Bewertung für die native Fähigkeit in Mit @capgo/capacitor-in-app-Bewertung, @capgo/capacitor-native-Markt für die Implementierungsdetail in @capgo/capacitor-native-Markt, und Mit @capgo/capacitor-native-Markt für die native Fähigkeit in Mit @capgo/capacitor-native-Markt.