iOS-Abonnementgruppe erstellen

Subscription Groups sind essenziell, um verschiedene Abo-Stufen in deiner iOS-App zu organisieren und zu verwalten. Das Verständnis ihrer Funktionsweise ist entscheidend für die Implementierung von Upgrades, Downgrades und Crossgrades.

Was ist eine Abo-Gruppe?

Eine Subscription Group ist eine Sammlung zusammengehöriger Abonnements, zwischen denen Nutzer wählen können. Ein Nutzer kann pro Gruppe immer nur ein Abo gleichzeitig aktiv haben. Beim Wechsel zwischen Abos übernimmt Apple den Übergang automatisch.

Warum Abo-Gruppen wichtig sind

Subscription Groups ermöglichen:

• Gestaffelte Preise: Angebote für Basic-, Premium- und Ultimate-Pläne
• Unterschiedliche Laufzeiten: Monatliche, jährliche und Lifetime-Optionen
• Upgrade-/Downgrade-Logik: Automatische Handhabung von Abo-Änderungen
• Vereinfachtes Management: Verwandte Abos zusammenfassen

Abonnement-Stufen

Innerhalb einer Gruppe sollte jedes Abo nach seinem Wert (Level 1 ist der höchste) eingestuft werden. Diese Rangfolge bestimmt die Klassifizierung von Abo-Änderungen:

Beispiele für Stufen

Level 1 (Höchster Wert)

• Premium Jährlich ($99.99/Jahr)
• Ultimate Monatlich ($19,99/Monat)

Level 2 (Mittlerer Wert)

• Standard Jährlich ($49,99/Jahr)
• Premium Monatlich ($9,99/Monat)

Level 3 (Niedrigster Wert)

• Basic Jährlich ($29,99/Jahr)
• Standard Monatlich ($4,99/Monat)

Typen von Abo-Änderungen

Apple verwaltet drei Arten von Abo-Änderungen automatisch basierend auf der Level-Rangfolge:

1. Upgrade

Wechsel zu einem höherwertigen Abo (z. B. Level 2 → Level 1).

Verhalten:

• Tritt sofort in Kraft
• Nutzer erhält anteilige Rückerstattung für die Restlaufzeit
• Neues Abo startet 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 lower-tier Abonnement (z. B. Level 1 → Level 2).

Verhalten:

• Takes effect at nächstem Verlängerungsdatum
• Nutzer behält aktuelles Abo bis zum Ende des Zeitraums
• Neues Abo startet automatisch nach Ablauf

Beispiel:

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

3. Crossgrade

Wechsel zu einem anderen Abo auf derselben Tarifstufe.

Verhalten hängt von der Laufzeit ab:

Unterschiedliche Laufzeit → Verhält sich wie Downgrade

• Wird zum nächsten Erneuerungsdatum wirksam
• Beispiel: Premium monatlich (Level 1) → Premium jährlich (Level 1)

Gleiche Dauer → Verhält sich wie Upgrade

• Takes effect immediately
• Beispiel: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

Erstellen einer Subscription Group

1. Zu Abonnements navigieren

   Wähle in App Store Connect deine App aus und gehe zu Monetarisierung > Abonnements.

2. Gruppe erstellen

   Klicken + neben „Subscription Groups“, um eine neue Gruppe zu erstellen.

3. Gruppe benennen

   Wähle einen aussagekräftigen Namen, der die enthaltenen Abonnements widerspiegelt:

   • „Premium Access“
   • „Cloud Storage Plans“
   • „Pro Features“

4. Abonnements hinzufügen

   Füge nach dem Erstellen der Gruppe einzelne Abonnements hinzu. Jedes Abonnement erhält ein Level-Ranking.

5. Level-Rankings festlegen

   Ordne die Abonnements vom höchsten (1) zum niedrigsten Wert. Beachte dabei:

   • Jahresabos stehen meist über Monatsabos
   • Teurere Tarife stehen über günstigeren
   • Ultimate-/Premium-Tiers haben die höchste Priorität

Nutzung in deiner App

Das native-purchases-Plugin kümmert sich automatisch um die Subscription-Group-Logik:

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);
});

Umgang mit Abo-Ä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();
  }
});

Kommunikation mit Nutzern

Kommuniziere immer klar, wie Änderungen ablaufen:

Bei Upgrades:

„Du erhältst sofortigen Zugriff auf Premium-Features. Dein aktuelles Abo wird anteilig verrechnet.“

Bei Downgrades:

„Dein Premium-Zugang bleibt bis zum [Verlängerungsdatum] bestehen, danach wechselst du zu Standard.“

Bei Crossgrades:

„Dein Plan wird bei der nächsten Verlängerung am [Datum] auf jährliche Abrechnung umgestellt.“

Server-Monitoring

Nutze Apples App Store Server Notifications v2 oder dein eigenes Backend zur Belegvalidierung, um StoreKit-Änderungen in deiner Datenbank zu spiegeln. Kombiniere Server-Notifications mit dem transactionUpdated Listener, damit Client und Backend synchron bleiben.

Best Practices

Gruppen-Organisation

• Verwandte Abonnements in derselben Gruppe halten
• Unterschiedliche Features nicht mischen (z. B. Speicher und Werbefreiheit)
• Separate Gruppen für verschiedene Feature-Sets erstellen

Ranking-Strategie für Stufen

• Jahrespläne → Höheres Level als Monatspläne (im selben Tier)
• Teurere Tiers → Höheres Level
• Mehrwert berücksichtigen, nicht nur den Preis

Nutzererfahrung

• Aktuelles Abo klar anzeigen
• Alle verfügbaren Optionen der Gruppe anzeigen
• Kennzeichnen, welche Änderungen sofort und welche zur Verlängerung greifen
• Einfaches Wechseln zwischen Plänen ermöglichen

Testen

• Alle Upgrade-Szenarien testen
• Alle Downgrade-Szenarien testen
• Crossgrade-Verhalten prüfen
• Webhook-Auslösung prüfen

Häufige Szenarien

Szenario 1: Dreistufige Monatspläne

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

• Basic → Premium: Upgrade (sofort)
• Premium → Ultimate: Upgrade (sofort)
• Ultimate → Premium: Downgrade (bei Verlängerung)
• Basic → Ultimate: Upgrade (sofort)

Szenario 2: Pläne mit gemischter Laufzeit

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

• Monatlich → Jährlich: Crossgrade (bei Verlängerung)
• Jährlich → Monatlich: Downgrade (bei Verlängerung)

Szenario 3: Mehrere Stufen und Laufzeiten

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)

Dieses Setup bietet maximale Flexibilität bei klarer Upgrade-/Downgrade-Logik.

Fehlerbehebung

Abonnement erscheint nicht in der Gruppe:

• Prüfen, ob es der richtigen Gruppe zugewiesen ist
• Status mindestens auf „Ready to Submit“ prüfen
• Sicherstellen, dass die Product ID korrekt ist

Falsches Upgrade-/Downgrade-Verhalten:

• Ranking der Ebenen prüfen (1 = höchste)
• Prüfen, ob die Abo-Stufen sinnvoll sind
• Kontrollieren, ob die Ebenen korrekt gesetzt sind

Produkte aus verschiedenen Gruppen:

• Nutzer können mehrere Gruppen gleichzeitig abonnieren
• Das ist Absicht – verwandte Produkte in eine Gruppe

getActiveProducts zeigt mehrere Abos an:

• Prüfen, ob Abos in unterschiedlichen Gruppen liegen
• Sicherstellen, dass kein Abo via Family Sharing läuft
• Abo-Status in App Store Connect prüfen

Weitere Ressourcen

Weitere Details findest du in der offizielle Apple-Dokumentation zu Subscription Groups.

Weiter mit Create iOS Subscription Group

Wenn du es nutzt iOS Subscription Group erstellen um Store-Zulassung und Distribution zu planen, verknüpfen Sie es mit @capgo/native-purchases verwenden für die native Funktionalität bei der Nutzung von @capgo/native-purchases, @capgo/capacitor-in-app-review für die Implementierungsdetails in @capgo/capacitor-in-app-review, @capgo/capacitor-in-app-review nutzen für die native Funktion bei der Nutzung von @capgo/capacitor-in-app-review, @capgo/capacitor-native-market für das Implementierungsdetail in @capgo/capacitor-native-market, und @capgo/capacitor-native-market nutzen für die native Funktionalität bei der Nutzung von @capgo/capacitor-native-market.