Crea iOS Gruppo di iscrizione

I gruppi di abbonamento sono essenziali per organizzare e gestire più livelli di abbonamento nella tua app iOS. Comprendere come funzionano è fondamentale per implementare le funzionalità di aggiornamento, downgrade e crossgrade.

Cos’è un gruppo di abbonamento?

Un gruppo di abbonamenti è una raccolta di abbonamenti correlati tra cui gli utenti possono scegliere. Gli utenti possono sottoscrivere un solo abbonamento alla volta all’interno di un gruppo. Quando cambiano abbonamento, Apple gestisce la transizione automaticamente.

Perché i gruppi di abbonamento sono importanti

I gruppi di sottoscrizione consentono:

• Prezzi scaglionati: offri piani base, premium e definitivi
• Durate diverse: opzioni mensili, annuali e a vita
• Logica di upgrade/downgrade: gestione automatica delle modifiche all’abbonamento
• Gestione semplificata: raggruppa insieme gli abbonamenti correlati

Livelli di abbonamento

All’interno di un gruppo, ciascuna sottoscrizione deve essere classificata dal valore più alto (livello 1) al valore più basso. Questa classifica determina come vengono classificate le modifiche all’abbonamento:

Esempi di livelli

Livello 1 (valore più alto)

• Premium annuale ($99,99/anno)
• Ultimate mensile ($ 19,99/mese)

Livello 2 (valore medio)

• Annuale standard ($49,99/anno)
• Premium mensile ($ 9,99/mese)

Livello 3 (valore più basso)

• Annuale di base ($ 29,99/anno)
• Mensile standard ($ 4,99/mese)

Tipi di modifica dell’abbonamento

Apple gestisce automaticamente tre tipi di modifiche all’abbonamento in base alla classifica del livello:

1. Aggiorna

Passaggio a un abbonamento di livello superiore (ad esempio, livello 2 → livello 1).

Comportamento:

• Ha effetto immediatamente
• L’utente riceve un rimborso proporzionale per il tempo rimanente
• Il nuovo abbonamento 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. Downgrade

Passaggio a un abbonamento di livello inferiore (ad esempio, livello 1 → livello 2).

Comportamento:

• Entra in vigore alla prossima data di rinnovo
• L’utente mantiene l’abbonamento corrente fino alla fine del periodo
• Il nuovo abbonamento 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. Valutazione incrociata

Passaggio a un altro abbonamento allo stesso livello.

Il comportamento dipende dalla durata:

Durata diversa → Si comporta come downgrade

• Entra in vigore alla prossima data di rinnovo
• Esempio: Premio mensile (Livello 1) → Premio annuale (Livello 1)

Stessa durata → Si comporta come aggiornamento

• Ha effetto immediato
• Esempio: Premium mensile (Livello 1) → Ultimate mensile (Livello 1)

Creazione di un gruppo di abbonamento

1. Vai a Abbonamenti

   In App Store Connect, seleziona la tua app e vai a Monetizza > Abbonamenti.

2. Crea gruppo

   Fai clic su ++ accanto a “Gruppi di abbonamento” per creare un nuovo gruppo.

3. Assegna un nome al gruppo

   Scegli un nome descrittivo che rifletta gli abbonamenti che contiene:

   • “Accesso Premium”
   • “Piani di archiviazione cloud”
   • “Funzioni professionali”

4. Aggiungi abbonamenti

   Dopo aver creato il gruppo, aggiungivi iscrizioni individuali. Ogni abbonamento avrà una classifica per livello.

5. Imposta classifiche di livelloDisporre gli abbonamenti dal valore più alto (1) al valore più basso. Considera:

   • I piani annuali in genere hanno un posizionamento migliore rispetto a quelli mensili
   • I livelli con il prezzo più alto si collocano sopra quelli con il prezzo più basso
   • I livelli Ultimate/Premium sono i più alti

Utilizzo nella tua app

Il plugin per gli acquisti nativi gestisce automaticamente la logica del gruppo di abbonamento:

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 delle modifiche all’abbonamento

Rilevamento del tipo di modifica

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 con l’utente

Comunicare sempre chiaramente il comportamento del cambiamento:

Per gli aggiornamenti:

“Avrai accesso immediato alle funzionalità Premium. Ripartiremo proporzionalmente il tuo abbonamento attuale.”

Per i downgrade:

“Manterrai l’accesso Premium fino al [data di rinnovo], poi passerai a Standard.”

Per i voti incrociati:

“Il tuo piano passerà alla fatturazione annuale al prossimo rinnovo il [data].”

Monitoraggio del server

Utilizza App Store Server Notifications v2 di Apple o il tuo backend di convalida delle ricevute per rispecchiare le modifiche di StoreKit nel tuo database. Associa le notifiche del server al listener transactionUpdated in modo che sia il client che il backend rimangano sincronizzati.

Migliori pratiche

Organizzazione del gruppo

• Mantieni gli abbonamenti correlati nello stesso gruppo
• Non combinare funzionalità non correlate (ad esempio archiviazione e rimozione degli annunci)
• Crea gruppi separati per diversi set di funzionalità

Strategia di classificazione dei livelli

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

Esperienza utente

• Mostra chiaramente l’abbonamento corrente
• Visualizza tutte le opzioni disponibili nel gruppo
• Indicare quali modifiche sono immediate rispetto al rinnovo
• Consentire un facile passaggio da un piano all’altro

Test

• Testare tutti gli scenari di aggiornamento
• Testare tutti gli scenari di downgrade
• Verificare il comportamento del crossgrade
• Controllare l’attivazione 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)

• Base → Premium: aggiornamento (immediato)
• Premium → Ultimate: aggiornamento (immediato)
• Ultimate → Premium: Downgrade (al rinnovo)
• Base → Ultimate: aggiornamento (immediato)

Scenario 2: Piani di durata mista

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

• Mensile → Annuale: Crossgrade (al rinnovo)
• Annuale → Mensile: Downgrade (al rinnovo)

Scenario 3: multilivello e durata multipla

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à pur mantenendo una chiara logica di aggiornamento/downgrade.

Risoluzione dei problemi

Abbonamento non visualizzato nel gruppo:

• Verificare che sia assegnato al gruppo corretto
• Verifica che sia almeno nello stato “Pronto per l’invio”.
• Assicurarsi che l’ID prodotto sia corretto

Comportamento errato di upgrade/downgrade:

• Classifiche a livello di revisione (1 = più alta)
• Verificare che i livelli di abbonamento abbiano senso
• Verificare che i livelli siano impostati correttamente

Prodotti di diversi gruppi:

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

getActiveProducts che mostra più abbonamenti:

• Controlla se gli abbonamenti sono in gruppi diversi
• Verifica che l’utente non sia iscritto tramite Condivisione famiglia
• Controlla lo stato dell’abbonamento in App Store Connect

Risorse aggiuntive

Per ulteriori dettagli, fare riferimento alla documentazione ufficiale Apple sui gruppi di abbonamento.