Erstelle iOS-Abonnement-Gruppe

Abonnementsgruppen sind für die Organisation und Verwaltung mehrerer Abonnementsstufen in Ihrer iOS-Anwendung unerlässlich. Ein Verständnis ihrer Funktionsweise ist für die Implementierung von Upgrade-, Downgrade- und Crossgrade-Funktionen entscheidend.

Was ist eine Abonnementsgruppe?

Ein Abonnementgruppe ist eine Sammlung von verwandten Abonnements, zwischen denen sich Benutzer entscheiden können. Benutzer können nur ein Abonnement innerhalb einer Gruppe gleichzeitig abonnieren. Wenn sie das Abonnement wechseln, übernimmt Apple die Übergabe automatisch.

Warum Abonnementgruppen wichtig sind

Abonnementgruppen ermöglichen:

• Stufenbezogene Preise: Grundlegende, Premium- und Ultimate-Pläne anbieten
• Verschiedene Laufzeiten: Monatliche, jährliche und lebenslange Optionen
• Upgrade/Downgrade-Logik: Automatische Verwaltung von Abonnementänderungen
• Einfache Verwaltung: Verwandte Abonnements zusammenfassen

Abonnementebenen

Innerhalb einer Gruppe sollten jedes Abonnement nach Wertigkeit von der höchsten (Ebene 1) bis zur niedrigsten bewertet werden. Diese Bewertung bestimmt, wie Abonnementänderungen klassifiziert werden:

Beispiel für Ebene

Ebene 1 (Höchster Wert)

• Premium-Jahresabonnement (99,99 €/Jahr)
• Ultimate-Monatsabonnement (19,99 €/Monat)

Ebene 2 (Mittlerer Wert)

• Standard Jahresabonnement (49,99 €/Jahr)
• Premium Monatsabonnement (9,99 €/Monat)

Level 3 (Niedrigster Wert)

• Basic Jahresabonnement (29,99 €/Jahr)
• Standard Monatsabonnement (4,99 €/Monat)

Abonnementänderungstypen

Apple handhabt automatisch drei Arten von Abonnementänderungen basierend auf der Level-Rangfolge:

1. Upgrade

Abschnitt mit dem Titel „1. Upgrade“ höherwertiger Abonnement (z.B. Level 2 → Level 1).

Verhalten:

• tritt in Kraft unmittelbar
• Benutzer erhält eine anteilige Rückerstattung für verbleibende Zeit
• Neues Abonnement beginnt sofort

Beispiel:

// User currently has: Standard Monthly (Level 2)
// User upgrades to: Premium Annual (Level 1)
// Result: Immediate access to Premium, refund for unused Standard time

2. Downgrade

Wechsel zu einem unteren Tarifplan (z.B. Level 1 → Level 2). Verhalten:

Wird am

• nächsten Verlängerungsdatum Der Benutzer hält die aktuelle Abonnement bis zum Ende des Abonnementzeitraums aufrecht.
• Das neue Abonnement beginnt automatisch nach Ablauf.
• Beispiel:

Auf die Zwischenablage kopieren

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

targetLanguage

Wechsel zu einer anderen Abonnement auf derselben Ebene.

Das Verhalten hängt von der Dauer ab:

Verschiedene Dauer → Verhält sich wie heruntergradieren

• Wird zum nächsten Rennovierungsdatum wirksam
• Beispiel: Monatliches Premium (Ebene 1) → Jährliches Premium (Ebene 1)

Selbe Dauer → Verhält sich wie aufbauen

• Wirkt sofort
• Beispiel: Premium Monatlich (Level 1) → Ultimate Monatlich (Level 1)

Erstellen Sie eine Abonnementgruppe

1. Navigieren Sie zu Abonnements

   In App Store Connect wählen Sie Ihr App und gehen Sie zu Monetize > Abonnements.

2. Erstellen Sie eine Gruppe

   Klicken Sie + nächstens zu „Abonnementgruppen“ um eine neue Gruppe zu erstellen.

3. Benennen Sie die Gruppe

   Wählen Sie einen beschreibenden Namen, der die in ihm enthaltenen Abonnements widerspiegelt:

   • “Premium-Zugriff”
   • “Cloud-Speicherkonzepte”
   • “Pro-Funktionen”

4. Abonnements hinzufügen

   Nachdem Sie die Gruppe erstellt haben, fügen Sie individuelle Abonnements hinzu. Jedes Abonnement wird eine Rangfolge haben.

5. Rangfolgen setzen

   Ordnen Sie die Abonnements von der höchsten Wertigkeit (1) bis zur niedrigsten Wertigkeit an. Beachten Sie:

   • Jährliche Pläne rangieren typischerweise höher als monatliche
   • Höherpreisige Tarife stehen über niedrigerpreisigen
   • Ultimative/ Premium-Tarife rangieren am höchsten

In Ihrer App verwenden

Die native-purchases-Plugin verarbeitet die Abonnementgruppenlogik automatisch:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Fetch all subscriptions in a group
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Display current subscription using StoreKit transactions
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const activeSubs = purchases.filter((purchase) => purchase.isActive);

// Detect pending downgrade/cancellation (StoreKit sets willCancel === true)
const pendingChange = purchases.find((purchase) => purchase.willCancel === true);
if (pendingChange) {
  console.log('Subscription will stop auto-renewing on', pendingChange.expirationDate);
}

// Purchase (StoreKit handles upgrades/downgrades automatically)
await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_annual',
  productType: PURCHASE_TYPE.SUBS,
});

// Listen for StoreKit updates (fires on upgrades/downgrades/refunds)
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription updated:', transaction);
});

Verwaltung von Abonnementänderungen

Änderungstyp erkennen

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Get current subscription info
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const currentSubscription = purchases.find(
  (purchase) => purchase.subscriptionState === 'subscribed',
);

if (currentSubscription) {
  // StoreKit reports if user cancelled auto-renew
  if (currentSubscription.willCancel) {
    console.log(
      `User cancelled. Access remains until ${currentSubscription.expirationDate}`,
    );
  }

  if (currentSubscription.isUpgraded) {
    console.log('User recently upgraded to this plan.');
  }
}

// Listen for automatic upgrades/downgrades
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription changed!', transaction);
  if (transaction.subscriptionState === 'revoked') {
    revokeAccess();
  } else if (transaction.isActive) {
    unlockPremiumFeatures();
  }
});

Benutzerkommunikation

Kommunizieren Sie das Änderungsverhalten immer klar:

Bei Upgrades:

„Sie erhalten sofortigen Zugriff auf Premium-Funktionen. Wir berechnen Ihre aktuelle Abonnementzeit entsprechend ab.“

Für Downgraden:

„Sie behalten den Premium-Zugriff bis [Stichtag], dann wechseln Sie auf Standard.“

Für Crossgrades:

„Ihr Plan wird sich bei der nächsten Erneuerung am [Datum] auf jährliche Abrechnung ändern.“

Serverüberwachung

Verwenden Sie Apples App Store Server Notifications v2 oder Ihren eigenen Receipt-Validierungsserver, um Änderungen an StoreKit in Ihrer Datenbank zu spiegeln. Paaren Sie Serverbenachrichtigungen mit dem transactionUpdated Hörer, damit sich sowohl Client als auch Backend synchron halten.

Gute Praktiken

Gruppenorganisation

• Verwaltung verwandter Abonnements in einer Gruppe
• Mische nicht verwandte Funktionen (z.B. Speicher und Werbung entfernen)
• Erstelle separate Gruppen für verschiedene Funktionen

Level Ranking Strategie

• Jahrespläne → Höherer Stufe als monatliche (für gleiche Ebene)
• Höherpreisige Ebenen → Höherer Stufe
• Betrachte Wert, nicht nur Preis

Benutzererfahrung

• Zeige aktuelles Abonnement klar an
• Zeige alle verfügbaren Optionen in der Gruppe an
• Angabe der sofortigen vs. bei der Erneuerung vorgenommenen Änderungen
• Einfache Umstellung zwischen Tarifen ermöglichen

Testen

• Alle Upgrade-Szenarien testen
• Alle Downgrade-Szenarien testen
• Verifizieren Sie das Verhalten bei der Kreuzgradierung
• Überprüfen Sie, ob Webhooks ausgelöst werden

Gemeinsame Szenarien

Szenario 1: Dreistufige monatliche Tarife

Level 1: Ultimate Monthly ($19.99)
Level 2: Premium Monthly ($9.99)
Level 3: Basic Monthly ($4.99)

• Basic → Premium: Upgrade (unmittelbar)
• Premium → Ultimate: Upgrade (unmittelbar)
• Ultimate → Premium: Downgrade (bei Erneuerung)
• Basic → Ultimate: Upgrade (unmittelbar)

Szenario 2: Mischung von Dauerdauerplänen

Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)

• Monatlich → Jahres: Crossgrade (bei Erneuerung)
• Jährlich → Monatlich: Downgrade (bei Erneuerung)

Szenario 3: Mehrschichtige Mehrdauerdauerpläne

Level 1: Ultimate Annual ($199/year)
Level 2: Ultimate Monthly ($19.99/month)
Level 3: Premium Annual ($99/year)
Level 4: Premium Monthly ($9.99/month)
Level 5: Basic Annual ($49/year)
Level 6: Basic Monthly ($4.99/month)

Diese Konfiguration bietet maximale Flexibilität, während die klare Upgrade-/Downgrade-Logik aufrechterhalten wird.

Fehlersuche

Abonnement erscheint nicht in der Gruppe:

• Überprüfen Sie, ob es der richtigen Gruppe zugewiesen ist
• Überprüfen Sie, ob es sich in mindestens dem Status “Bereit zum Einreichen” befindet
• Stellen Sie sicher, dass die Produkt-ID korrekt ist

Falsches Upgrade-/Downgrade-Verhalten:

• Überprüfen Sie die Rangfolge der Level (1 = höchstes)
• Überprüfen Sie, ob die Abonnementstufen Sinn ergeben
• Überprüfen Sie, ob die Level korrekt eingestellt sind

Produkte aus verschiedenen Gruppen:

• Benutzer können gleichzeitig mehrere Gruppen abonnieren
• Dies ist bewusst geplant - Halten Sie verwandte Produkte in derselben Gruppe

getActiveProducts zeigt mehrere Abonnements an:

• Überprüfen Sie, ob die Abonnements in verschiedenen Gruppen sind
• Stellen Sie sicher, dass der Benutzer nicht über Family Sharing abonniert ist
• Überprüfen Sie den Abonnementstatus in App Store Connect

Zusätzliche Ressourcen

Zur weiteren Information wenden Sie sich an die offizielle Apple-Dokumentation zu Abonnementgruppen.