Zum Starten

Installation

Sie können unsere KI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten zu Ihrer KI-Tool 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 den 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 mit native Projekten

   bunx cap sync

3. Kostenlose Unterstützung 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 monatliche Verpflichtungspläne

   Wenn ein unterstützter iOS-Abonnement zurückgegeben wird pricingTermskann billingPlanType: 'monthly' Sie eine monatliche Abrechnungsoption mit einer 12-monatigen Verpflichtung anbieten und purchaseProduct()zu . Siehe iOS monatliche Verpflichtungsabrechnungspläne

   für den vollständigen Fluss.
   • Android
     
   • Erstellen Sie in-App-Produkte und -Abonnements in App Store Connect.
     
   • Verwenden Sie StoreKit Local Testing oder Sandbox-Tester für QA-Tests.Keine Manifest-Änderungen erforderlich. Stellen Sie sicher, dass Ihre Produkte genehmigt sind.
   iOS
   • Erstellen Sie in-app-Produkte und -Abonnements im Google Play Console.
     
   • Hochladen Sie mindestens eine interne Testversion 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 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 im App Store Connect / Google Play Console konfiguriert.
productType	Android nur	PURCHASE_TYPE.INAPP oder PURCHASE_TYPE.SUBS. Standardmäßig INAPP. Immer auf SUBS für Abonnements.
planIdentifier	Android-Abonnements	Base-Plan-ID aus Google Play Console. Erforderlich für Abonnements, ignoriert auf iOS und bei In-App-Käufen.
billingPlanType	iOS-Abonnements	StoreKit-Billing-Plan 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	Eine UUID/Zeichenkette, die den Kauf mit Ihrem Benutzer verbindet. Erforderlich, dass es auf iOS eine UUID ist; Android akzeptiert jede verschlüsselte Zeichenkette bis zu 64 Zeichen.
isConsumable	Android	Setzen Sie auf true um automatisch Token nach der Gewährung von Entgelt für Verbrauchsgüter zu konsumieren. Standardmäßig false.

Entgeltstatus überprüfen

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-Belegvalidierung.
• Android: isActive/expirationDate werden nicht befüllt; rufen Sie den Google Play-Entwickler API mit dem purchaseToken für die verbindliche Statusanzeige. purchaseState müssen 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, den lokalisierten Titel, die Beschreibung, die Einführungsangebote und die unterstützten iOS-Preisbegriffe.
• purchaseProduct() – Starten Sie den Kauffluss von StoreKit 2 oder Billing-Klient, einschließlich iOS-Monatsverpflichtungsabrechnungsplänen.
• restorePurchases() – Wiederholen Sie historische Käufe 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 die laufenden StoreKit 2-Transaktionen, wenn Ihr App startet (nur iOS).

Gute Praktiken

1. Ladenpreise anzeigen – Apple erfordert die Anzeige von product.title und product.priceString; programmatische Eingaben niemals festlegen.
2. Verwenden Sie appAccountToken – bestimmt generieren Sie ein 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 Benutzerstornierungen, Netzwerkfehler und nicht unterstützte Bezahlumgebungen.
5. Sorgfältig testen – folge der iOS-Sandbox-Leitfaden und Android-Sandbox-Leitfaden.
6. Wiederherstellung und Verwaltung anbieten – füge UI-Schaltflächen hinzu, die an restorePurchases() und manageSubscriptions().

Einnahmen-Schritte

Nachdem der Kauffluss funktioniert, verwende das Einnahmen-Playbook Ihre erste bezahlte Kanalstrategie planen: Produktumfang, Auffindbarkeit im Store, Preisgestaltung, Paywall-Platzierung, Analysen und Rückmeldung zu Abbruchraten.

Fehlersuche

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) bzw. aktiviert (Google Play) sind.
• Warten Sie einige Stunden nach der Erstellung von Produkten; die Store-Verbreitung ist nicht sofort.

Kauf abgebrochen oder hängen geblieben

• Benutzer können mitten im Flow abbrechen; umschließen Sie Aufrufe mit try/catch und präsentieren Sie freundliche Fehlermeldungen.
• 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.

Abonnementzustand ist falsch

• Verwenden Sie getPurchases() um den Speicherdaten mit Ihrem lokalen Berechtigungscache zu vergleichen.
• Bei Android wird immer der Google Play Developer API abgefragt, um purchaseToken um Ablaufdaten oder Rückerstattungsstatus zu erhalten.
• Bei iOS prü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 zur Planung der Ladenfreigabe und -distribution 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 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.