Crea un Gruppo di Abbonamento iOS

Subscription groups are essential for organizing and managing multiple subscription levels in your iOS app. Understanding how they work is crucial for implementing upgrade, downgrade, and crossgrade functionality.

Cosa è un Gruppo di Abbonamento?

A subscription group is a collection of related subscriptions that users can choose between. Users can only subscribe to one subscription within a group at a time. When they switch subscriptions, Apple handles the transition automatically.

Perché i Gruppi di Abbonamento sono Importanti

Iscrizioni a gruppi abilitano:

• I gruppi di abbonamento consentono:Offri: piani base, premium e ultimate
• Diversi periodi: Opzioni mensili, annuali e a vita
• Logica di aggiornamento/abbassamento: Gestione automatica delle modifiche di abbonamento
• Gestione semplificata: Raggruppa insieme gli abbonamenti correlati

Niveaux di abbonamento

All'interno di un gruppo, ogni sottoscrizione dovrebbe essere classificata in base al valore più alto (livello 1) e al valore più basso. Questa classificazione determina come vengono classificate le modifiche alle sottoscrizioni:

Esempi di livello

Livello 1 (Valore più alto)

• Prenotazione annuale Premium (99,99 €/anno)
• Prenotazione mensile Premium (19,99 €/mese)

Livello 2 (Valore medio)

• Prenotazione annuale Standard (49,99 €/anno)
• Prenotazione mensile Premium (9,99 €/mese)

Livello 3 (Valore più basso)

• Prenotazione annuale Base (29,99 €/anno)
• Prenotazione mensile Standard (4,99 €/mese)

Tipi di Cambiamento di Abbonamento

Apple gestisce automaticamente tre tipi di modifiche delle sottoscrizioni in base al livello di classifica:

1. Aggiornamento

Passare a un higher-tier abbonamento (ad esempio, livello 2 → livello 1).

Ha effetto

• immediato L'utente riceve
• 1. Downgrade rimborso proporzionato per il tempo residuo
• La nuova sottoscrizione inizia subito

Esempio:

// 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. Riduzione del livello

Passaggio a una lower-tier abbonamento (ad esempio, livello 1 → livello 2).

Ha effetto a

• rimborso proporzionato data di rinnovo successivo
• L'utente mantiene la sottoscrizione corrente fino alla fine del periodo
• La nuova sottoscrizione inizia automaticamente dopo la scadenza

Esempio:

// 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. Aggiornamento di categoria

Passaggio a un'altra sottoscrizione allo stesso livello di tariffa.

Il comportamento dipende dalla durata:

Durata diversa → Si comporta come abbassamento

• Ha effetto alla data di rinnovo successiva
• Esempio: Premium Mensile (Livello 1) → Premium Annuale (Livello 1)

Durata identica → Si comporta come aggravamento

• Ha effetto immediatamente
• Esempio: Premium Mensile (Livello 1) → Ultimate Mensile (Livello 1)

Creazione di un Gruppo di Abbonamenti

1. Naviga alle Abbonamenti

   In App Store Connect, seleziona il tuo app e vai a Monetizza > Abbonamenti.

2. Crea Gruppo

   Clicca + su “Gruppi di Abbonamento” per creare un nuovo gruppo.

3. Dai un Nome al Gruppo

   Scegli un nome descrittivo che rifletta gli abbonamenti che contiene:

   • “Accesso Premium”
   • “Piani di Archiviazione Cloud”
   • “Caratteristiche Pro”

4. Aggiungi Abbonamenti

   Dopo aver creato il gruppo, aggiungi gli abbonamenti individuali. Ogni abbonamento avrà un livello di classificazione.

5. Configura Classificazioni di Livello

   Ordina le sottoscrizioni dal valore più alto (1) al valore più basso. Considera:

   • Annual plans typically rank higher than monthly
   • Livelli più costosi si collocano sopra quelli a prezzi inferiori
   • Ultimate/premium tiers rank highest

Utilizzo nell'App

Il plugin native-purchases gestisce automaticamente la logica del gruppo di sottoscrizioni:

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

Gestione dei Cambiamenti di Sottoscrizione

Rilevamento del Tipo di Cambio

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

Comunicazione utente

Comunica sempre chiaramente il comportamento di modifica:

Forse Aggiornamenti:

“Avrai accesso immediato alle funzionalità Premium. Ti verrà prorata la tua sottoscrizione corrente.”

Forse Riduzioni:

“Mantieni l'accesso Premium fino alla [data di rinnovo], poi passa a Standard.”

Forse Cambiamenti di piano:

“Il tuo piano cambierà a fatturazione annuale alla prossima rinnovazione il [data].”

Monitoraggio server

Utilizza le notifiche del server di Apple Store v2 o il tuo backend di validazione di ricevuta per riflettere le modifiche di StoreKit nel tuo database. Pair le notifiche del server con il transactionUpdated listener per mantenere sincronizzati sia il client che il backend.

Pratiche raccomandate

Organizzazione dei gruppi

• Tenere le sottoscrizioni correlate nel medesimo gruppo
• Don’t mix unrelated features (e.g., storage and ad removal)
• Creare gruppi separati per set di funzionalità diverse

Strategia di classificazione dei livelli

• Piani annuali → Livello superiore rispetto al mensile (per stesso livello)
• Livelli di prezzo più alti → Livello superiore
• Considera il valore, non solo il prezzo

Esperienza Utente

• Mostra la sottoscrizione corrente chiaramente
• Visualizza tutte le opzioni disponibili nel gruppo
• Indica quali cambiamenti sono immediati vs. a rinnovo
• Consenti di passare facilmente tra i piani

Test

• Testa tutti gli scenari di aggiornamento
• Testa tutti gli scenari di riduzione
• Verifica il comportamento di crossgrade
• Controlla l'invio del webhook

Scenari comuni

Scenario 1: Piani mensili a tre livelli

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

• Di base → Premium: Aggiorna (immediato)
• Premium → Ultimo: Aggiorna (immediato)
• Ultimo → Premium: Riduci (alla rinnovazione)
• Di base → Ultimo: Aggiorna (immediato)

Scenario 2: Piani di durata mista

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

• Da mensile a annuale: Crossgrade (al rinnovo)
• Da annuale a mensile: Downgrade (al rinnovo)

Scenario 3: Multi-Tier Multi-Durata

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)

Questa configurazione offre la massima flessibilità mantenendo una logica di aggiornamento/scadenzamento chiara.

Troubleshooting

La sottoscrizione non compare nel gruppo:

• Verifica che sia assegnata al gruppo corretto
• Verifica che sia in almeno lo stato "Pronto per la pubblicazione"
• Assicurati che l'ID del prodotto sia corretto

Wrong upgrade/downgrade behavior:

• Verifica le classifiche di livello (1 = più alto)
• Verifica che i livelli dei abbonamenti siano sensati
• Verifica che i livelli siano impostati correttamente

Prodotti da gruppi diversi:

• Gli utenti possono sottoscrivere a più gruppi contemporaneamente
• Questo è intenzionale - mantieni i prodotti correlati nello stesso gruppo

getActiveProducts mostra più abbonamenti:

• Verifica se gli abbonamenti sono in gruppi diversi
• Verifica che l'utente non sia abbonato tramite Family Sharing
• Verifica lo stato della sottoscrizione in App Store Connect

Risorse aggiuntive

Per ulteriori informazioni, si rinvia alla documentazione ufficiale di Apple sui gruppi di sottoscrizioni.

Continua da Creazione di un gruppo di sottoscrizione iOS

Se stai utilizzando Creazione di un gruppo di sottoscrizione iOS per pianificare l'approvazione e la distribuzione della store, connettilo con Utilizza @capgo/native-purchases per la capacità nativa in Utilizza @capgo/native-purchases, @capgo/capacitor-recensione-in-app per il dettaglio di implementazione in @capgo/capacitor-in-app-review Utilizzando @capgo/capacitor-in-app-review per la capacità nativa in Utilizzando @capgo/capacitor-in-app-review @capgo/capacitor-market nativo per il dettaglio di implementazione in @capgo/capacitor-native-market, e Utilizzando @capgo/capacitor-native-market per la capacità nativa in Utilizzando @capgo/capacitor-native-market