Zum Starten

Installation

Sie können unsere AI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Werkzeug mithilfe 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 angegebenen Plattform-spezifischen Anweisungen:

1. Installieren Sie das Paket

   bun add @capgo/native-purchases

2. Synchronisieren Sie mit native Projekten

   bunx cap sync

3. Kostenlose Abrechnung überprü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 Geschäften 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. 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ütztes iOS-Abonnement zurückgegeben wird pricingTermsSie können eine monatliche Abrechnungsoption mit einer 12-monatigen Verpflichtung anzeigen und eine Abrechnung übermitteln billingPlanType: 'monthly' zu purchaseProduct(). Siehe iOS-Monatsverpflichtungsberechnungspläne für den vollständigen Ablauf.

   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 in-App-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 Abrechnungs-Erlaubnis hinzu AndroidManifest.xml:

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

Beispiel für den Kauf einer Dienstleistung

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 für Android	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBS. Standardmäßig ist INAPP. Immer auf SUBS für Abonnements.
planIdentifier	Android-Abonnements	Basiskunden-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 'monthly' für monatliche Abrechnung mit einer 12-monatigen Verpflichtung, wenn product.pricingTerms für iOS
quantity	Nur für In-App-Käufe, standardmäßig ist	Nur für In-App-Käufe 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 nach der Gewährung von Verbrauchsgütern automatisch Token zu konsumieren. Standardmäßig ist dies auf false.

Prüfen Sie den Status der Berechtigung

Verwenden Sie getPurchases() für eine plattformübergreifende Ansicht aller 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

• iOSZu den Abonnements gehören isActive, expirationDate, willCancel, und Unterstützung für den StoreKit 2-Hörer. In-App-Käufe erfordern die Validierung des Server-Einkaufsbelegs.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie die Google Play-Entwickler-API mit dem purchaseToken zur Autoritätsstatus ab. purchaseState muss sein PURCHASED und isAcknowledged muss sein true.

API Schnellreferenz

• isBillingSupported() – prüfen Sie die Verfügbarkeit von StoreKit / Google Play.
• getProduct() / getProducts() – Preis, lokalisierte Überschrift, Beschreibung, Einführungsangebote und unterstützte iOS-Preistypen abrufen.
• purchaseProduct() – StoreKit 2 oder Billing-Kundenkaufstrom starten, einschließlich iOS-Monatsverpflichtungsabrechnungsplänen.
• restorePurchases() – historische Kaufgeschäfte wiederholen und auf dem aktuellen Gerät synchronisieren.
• getPurchases() – alle iOS-Transaktionen oder Play Billing-Käufe auflisten.
• manageSubscriptions() – die native Abonnementverwaltungsoberfläche öffnen.
• addListener('transactionUpdated') – beim Start Ihrer App die laufenden StoreKit 2-Transaktionen bearbeiten (nur iOS).

Gute Praktiken

1. Preise im Store anzeigen – Apple erfordert die Anzeige von product.title und product.priceString; nie speichern Sie es hartcodiert.
2. Verwenden Sie appAccountToken – generieren Sie deterministisch eine UUID (v5) aus Ihrem Benutzer-ID, um Kaufe mit Konten zu verbinden.
3. Überprüfen Sie serverseitig – senden Sie receipt (iOS) / purchaseToken (Android) an Ihren Backend-Server zur Verifizierung.
4. Behandeln Sie Fehler geschickt – überprüfen Sie Benutzer-Stornierungen, Netzwerkfehler und nicht unterstützte Bezahlumgebungen.
5. Testen Sie gründlich – folgen Sie dem iOS Sandbox-Leitfaden und Android-Sandbox-Leitfaden.
6. Angebot wiederherstellen & Verwaltung – Hinzufügen von UI-Schaltflächen, die an restorePurchases() und manageSubscriptions().

Ertrags-Schritte

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

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 mitten im Flow abbrechen; Wrap Aufrufe in try/catch und Oberflächenfreundliche Fehlermeldungen anbieten.
• Für Android stellen Sie sicher, dass Testkonten die App vom Play Store (internes Track) installieren, damit Billing funktioniert.
• Überprüfen Sie Logcat/Xcode für Zahlungsfehler, wenn Sie auf einem Gerät laufen.

Falsche Abonnementzustand

• Verwenden Sie getPurchases() um Store-Daten mit Ihrem lokalen Berechtigungscache zu vergleichen.
• Auf Android fragen Sie immer den Google Play Developer API an, um purchaseToken die Ablaufdaten oder den Status der Rückerstattung zu erhalten.
• Auf iOS überprüfen Sie isActive/expirationDate und validieren Sie die Rechnungen, um Rückerstattungen oder Widerrufe zu erkennen.

Weitergehen von Getting Started

Wenn Sie Getting Started zur 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-Bewertung für die Implementierungsdetails 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 Implementierungsdetails in @capgo/capacitor-native-Markt und Mit @capgo/capacitor-native-Markt für die native Fähigkeit in Mit @capgo/capacitor-native-Markt.