Erstellen Sie eine iOS-Abonnementgruppe

Abonnementgruppen sind für die Organisation und Verwaltung mehrerer Abonnementebenen in Ihrer iOS-Anwendung unerlässlich. Die Kenntnis ihrer Funktionsweise ist entscheidend für die Implementierung von Upgrade-, Downgrade- und Crossgrade-Funktionen.

Was ist eine Abonnementgruppe?

Eine Abonnementgruppe ist eine Sammlung verwandter Abonnements, zwischen denen sich die Benutzer wählen können. Die Benutzer können sich nur auf ein Abonnement innerhalb einer Gruppe gleichzeitig abonnieren. Wenn sie das Abonnement wechseln, übernimmt Apple die Übergabe automatisch.

Warum Gruppen für Abonnements wichtig sind

Abonnementsgruppen ermöglichen:

• Stufenbezogene Preise: Grundlegende, Premium- und Ultimate-Pläne anbieten
• Verschiedene Laufzeiten: Monatliche, jährliche und lebenslange Optionen
• Upgrade/Downgrade-Logik: Automatisches Handling von Abonnementänderungen
• Einfache Verwaltung: Gruppieren Sie verwandte Abonnements zusammen

Abonnementebenen

Innerhalb einer Gruppe sollten alle Abonnements nach Wert (Ebene 1) bis zum niedrigsten Wert gerankt werden. Diese Rangfolge bestimmt, wie Abonnementänderungen klassifiziert werden:

Beispiel für Ebene

(Höchster Wert) Premium-Jahresabonnement (99,99 €/Jahr)

• Ultimate-Monatsabonnement (19,99 €/Monat)
• Beispiel für Ebene

(Mittlerer Wert) Standard-Jahresabonnement (49,99 €/Jahr)

• Beispiel für Ebene
• Premium Monatlich (9,99 €/Monat)

Level 3 (Niedrigster Wert)

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

Abonnementänderungstypen

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

1. Upgrade

Zum einer höheren Ebene Abonnement (z.B. Level 2 → Level 1).

Verhalten:

• Wird sofort wirksam. unmittelbar
• Benutzer erhält eine anteilige Rückerstattung für die 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

Wechseln Sie zu einer __CAPGO_KEEP_0__Niveau (z.B. Level 1 → Level 2). Verhalten:

Wird zum ersten Mal am

• __CAPGO_KEEP_1__Renewal-Datum Der Benutzer hält die aktuelle Abonnement bis zum Ende des Abonnementzeitraums bei.
• 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

Abschnitt mit dem Titel „3. Crossgrade“

Wechseln Sie zu einer anderen Abonnement auf dem gleichen Ebenen.

Das Verhalten hängt von der Dauer ab:

Verschiedene Dauer → Verhält sich wie herabstufen

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

Selbe Dauer → Verhält sich wie aufstufen

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

Erstellen Sie eine Abonnementgruppe

1. Navigieren Sie zu Abonnements

   Wählen Sie in App Store Connect Ihr App und gehen Sie zu Monetize > Abonnements.

2. Erstellen Sie eine Gruppe

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

3. Benennen Sie die Gruppe

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

   • „Premium-Zugang“
   • “Cloud Storage-Pläne”
   • “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 höher als monatliche
   • Höherpreisige Tarife stehen über niedrigerpreisigen
   • Ultimative/Premium-Tarife rangieren am höchsten

Verwendung in Ihrer App

Der native-purchases-Plugin handhabt die Abonnement-Gruppen-Logik 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();
  }
});

Benutzerverkündigung

Klare Kommunikation über die Änderung vermitteln:

Bei Upgrades:

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

Bei Downgrades:

“Sie behalten den Premium-Zugriff bis [renewal date], dann wechseln Sie auf Standard.”

Für Crossgrades:

“Ihr Plan wird sich bei der nächsten Erneuerung am [date] 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 "listener" so, dass sowohl Client als auch Backend synchron bleiben. transactionUpdated Gute Praktiken

Abschnitt mit dem Titel “Gute Praktiken”

Abschnitt mit dem Titel “Gruppenorganisation”

• __CAPGO_KEEP_0__
• Mische keine unabhängigen Funktionen (z.B. Speicherung und Werbung entfernen)
• Erstelle separate Gruppen für unterschiedliche Funktionssets

Level Ranking Strategie

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

Benutzererfahrung

• Zeige aktuelle Abonnement offensichtlich
• Zeige alle verfügbaren Optionen in der Gruppe an
• Anzeige, welche Änderungen sofort vs. bei Verlängerung sind
• Zum einfachen Wechsel zwischen Tarifen zulassen

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: Sofortige Upgrade
• Premium → Ultimate: Sofortige Upgrade
• Ultimate → Premium: Downgraden (bei Erneuerung)
• Basic → Ultimate: Sofortige Upgrade

Szenario 2: Mischung von Laufzeitenplänen

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

• Monatlich → Jahres: Crossgraden (bei Erneuerung)
• Jährlich → Monatlich: Downgraden (bei Erneuerung)

Szenario 3: Mehrschichtige Mehrdauerplä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 Einrichtung 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
• Stellen Sie sicher, dass 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 Ranglisten (1 = höchstes)
• Stellen Sie sicher, dass die Abonnementstufen Sinn ergeben
• Überprüfen Sie, ob die Ebenen korrekt eingestellt sind

Produkte aus verschiedenen Gruppen:

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

getActiveProducts zeigt mehrere Abonnements an:

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

Zusätzliche Ressourcen

Weitere Informationen finden Sie in der offiziellen Apple-Dokumentation zu Abonnementgruppen.