Créer un groupe d'abonnements iOS

Les groupes d'abonnement sont essentiels pour organiser et gérer plusieurs niveaux d'abonnement dans votre application iOS. Comprendre leur fonctionnement est crucial pour implémenter les fonctionnalités de montée, descente ou changement de gamme (crossgrade).

Qu'est-ce qu'un groupe d'abonnement ?

Un groupe d'abonnement est un ensemble d'abonnements liés entre lesquels les utilisateurs peuvent choisir. Un utilisateur ne peut souscrire qu'à un seul abonnement au sein d'un groupe à la fois. Lorsqu'il change d'abonnement, Apple gère la transition automatiquement.

Pourquoi les groupes d'abonnement sont importants

Les groupes d'abonnement permettent :

• Une tarification par paliers: Proposer des plans basic, premium et ultimate
• Différentes durées: Des options mensuelles, annuelles et à vie
• La logique d'upgrade/downgrade: Gestion automatique des changements d'abonnement
• Gestion simplifiée: Regroupez les abonnements liés

Niveaux d'abonnement

Au sein d'un groupe, chaque abonnement doit être classé du plus haut niveau (niveau 1) au plus bas. Ce classement détermine la classification des changements d'abonnement :

Exemples de niveaux

Niveau 1 (Valeur la plus élevée)

• Premium Annuel (99,99 $/an)
• Ultimate mensuel (19,99 $/mois)

Niveau 2 (Valeur moyenne)

• Standard annuel (49,99 $/an)
• Premium mensuel (9,99 $/mois)

Niveau 3 (Valeur la plus basse)

• Basic annuel (29,99 $/an)
• Standard mensuel (4,99 $/mois)

Types de changement d'abonnement

Apple gère automatiquement trois types de changements d'abonnement selon le classement des niveaux :

1. Upgrade

Passage à un higher-tier abonnement (ex: niveau 2 → niveau 1).

Comportement :

• Prend effet immédiatement
• L'utilisateur reçoit un remboursement au prorata pour le temps restant
• Le nouvel abonnement débute aussitôt

Exemple :

// 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

Passage à un lower-tier inférieur (ex: niveau 1 → niveau 2).

Comportement :

• Prend effet à la prochaine date de renouvellement
• L'utilisateur conserve l'abonnement actuel jusqu'à la fin de la période
• Le nouvel abonnement débute automatiquement après l'expiration

Exemple :

// 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

Passage à un autre abonnement au même niveau de groupe.

Le comportement dépend de la durée :

Durée différente → Se comporte comme un downgrade

• Prend effet à la prochaine date de renouvellement
• Exemple : Premium mensuel (Niveau 1) → Premium annuel (Niveau 1)

Même durée → Se comporte comme upgrade

• Prend effet immédiatement
• Exemple : Premium Mensuel (Niveau 1) → Ultimate Mensuel (Niveau 1)

Créer un groupe d'abonnements

1. Accédez à Subscriptions

   Dans App Store Connect, sélectionnez votre app et allez dans Monétisation > Abonnements.

2. Créer un groupe

   Cliquez + à côté de « Groupes d'abonnement » pour créer un nouveau groupe.

3. Nommer le groupe

   Choisissez un nom descriptif qui reflète les abonnements qu'il contient :

   • « Accès Premium »
   • « Forfaits de stockage cloud »
   • « Fonctionnalités Pro »

4. Ajouter des abonnements

   Après avoir créé le groupe, ajoutez-y les abonnements individuels. Chaque abonnement aura un niveau de classement.

5. Définir les niveaux de classement

   Organisez les abonnements du plus avantageux (1) au moins avantageux. Prenez en compte :

   • Les forfaits annuels sont généralement mieux classés que les mensuels
   • Les paliers plus chers sont classés au-dessus des moins chers
   • Les paliers Ultimate/premium sont les plus élevés

Utilisation dans votre application

Le plugin native-purchases gère automatiquement la logique des groupes d'abonnement :

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

Gestion des changements d'abonnement

Détection du type de changement

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

Communication utilisateur

Communiquez toujours clairement les effets du changement :

Pour les upgrades :

« Vous aurez immédiatement accès aux fonctionnalités Premium. Votre abonnement actuel sera calculé au prorata. »

Pour les downgrades :

« Vous conserverez l'accès Premium jusqu'au [date de renouvellement], puis vous passerez au plan Standard. »

Pour les changements de plan :

« Votre plan passera en facturation annuelle lors du prochain renouvellement, le [date]. »

Surveillance du serveur

Utilisez les App Store Server Notifications v2 d'Apple ou votre propre backend de validation de reçus pour refléter les changements StoreKit dans votre base de données. Associez les notifications serveur au transactionUpdated listener pour que le client et le backend restent synchronisés.

Bonnes pratiques

Organisation des groupes

• Regroupez les abonnements liés dans le même groupe
• Don’t mix unrelated features (e.g., storage and ad removal)
• Créez des groupes distincts pour différents ensembles de fonctionnalités

Stratégie de classement des niveaux

• Plans annuels → Niveau supérieur aux plans mensuels (pour un même palier)
• Paliers plus chers → Niveau supérieur
• Privilégiez la valeur, pas seulement le prix

Expérience utilisateur

• Afficher clairement l'abonnement actuel
• Afficher toutes les options disponibles dans le groupe
• Indiquer les changements immédiats et ceux appliqués au renouvellement
• Permettre de changer de plan facilement

En test

• Tester tous les scénarios d'upgrade
• Tester tous les scénarios de downgrade
• Vérifier le comportement du crossgrade
• Vérifier le déclenchement du webhook

Scénarios courants

Scénario 1 : plans mensuels à trois niveaux

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

• Basic → Premium : Upgrade (immédiat)
• Premium → Ultimate : Upgrade (immédiat)
• Ultimate → Premium : Downgrade (au renouvellement)
• Basic → Ultimate : Upgrade (immédiat)

Scénario 2 : plans à durées mixtes

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

• Mensuel → Annuel : Crossgrade (au renouvellement)
• Annuel → Mensuel : downgrade (au renouvellement)

Scénario 3 : plusieurs niveaux et durées

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)

Cette configuration offre une flexibilité maximale tout en conservant une logique claire d'upgrade/downgrade.

Troubleshooting

L'abonnement n'apparaît pas dans le groupe :

• Vérifiez qu'il est assigné au bon groupe
• Vérifiez qu'il a au moins le statut « Prêt à être envoyé »
• Assurez-vous que l'ID du produit est correct

Comportement d'upgrade/downgrade incorrect :

• Review level rankings (1 = highest)
• Vérifiez la cohérence des niveaux d'abonnement
• Check that levels are set correctly

Produits de groupes différents :

• Les utilisateurs peuvent s'abonner à plusieurs groupes simultanément
• C'est voulu : gardez les produits liés dans le même groupe

getActiveProducts affiche plusieurs abonnements :

• Vérifiez si les abonnements sont dans des groupes différents
• Vérifiez que l'utilisateur n'est pas abonné via le partage familial
• Vérifiez le statut de l'abonnement dans App Store Connect

Ressources complémentaires

Pour plus de détails, consultez la documentation officielle d'Apple sur les groupes d'abonnement.

Continuer depuis « Créer un groupe d'abonnements iOS »

Si vous utilisez Créer un groupe d'abonnements iOS pour planifier la validation et la distribution sur le store, connectez-l’à Utiliser @capgo/native-purchases pour la capacité native dans Utiliser @capgo/native-purchases @capgo/capacitor-in-app-review pour le détail d'implémentation dans @capgo/capacitor-in-app-review, Utiliser @capgo/capacitor-in-app-review pour la capacité native dans Utiliser @capgo/capacitor-in-app-review, @capgo/capacitor-native-market pour le détail d'implémentation dans @capgo/capacitor-native-market, et Utiliser @capgo/capacitor-native-market pour la capacité native dans Utiliser @capgo/capacitor-native-market.