Crea gruppo di abbonamento iOS

I gruppi di abbonamento sono essenziali per organizzare e gestire diversi livelli di abbonamento nella tua app iOS. Capire come funzionano è fondamentale per implementare le logiche di upgrade, downgrade e crossgrade.

Cos'è un Subscription Group?

Un subscription group è una collezione di abbonamenti correlati tra cui l'utente può scegliere. Un utente può attivare un solo abbonamento per gruppo alla volta. Quando cambia piano, Apple gestisce la transizione automaticamente.

Perché i Subscription Group sono importanti

I subscription group permettono di gestire:

• Prezzi a livelli: Piani basic, premium e ultimate
• Diverse durate: Opzioni mensili, annuali e lifetime
• Logica di upgrade/downgrade: Gestione automatica dei cambi di abbonamento
• Gestione semplificata: Raggruppa abbonamenti correlati

Livelli di abbonamento

All'interno di un gruppo, ogni abbonamento deve essere ordinato dal valore più alto (livello 1) al più basso. Questo ordine determina come vengono classificati i cambiamenti di abbonamento:

Esempi di livelli

Livello 1 (Valore più alto)

• Premium Annual ($99.99/anno)
• Ultimate Mensile ($19.99/mese)

Livello 2 (Valore Medio)

• Standard Annuale ($49.99/anno)
• Premium Mensile ($9.99/mese)

Livello 3 (Valore Minimo)

• Basic Annuale ($29.99/anno)
• Standard Mensile ($4.99/mese)

Tipi di modifica dell'abbonamento

Apple gestisce automaticamente tre tipi di modifiche all'abbonamento in base alla classifica dei livelli:

1. Aggiorna

Passaggio a un higher-tier abbonamento (es. livello 2 → livello 1).

Comportamento:

• Entra in vigore immediatamente
• L'utente riceve un rimborso pro quota per il tempo residuo
• Il nuovo abbonamento parte 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 piano inferiore (es. livello 1 → livello 2).

Comportamento:

• Entra in vigore alla prossima data di rinnovo
• L'utente mantiene l'abbonamento attuale fino alla fine del periodo
• Il nuovo abbonamento parte 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. Crossgrade

Passaggio a un altro abbonamento allo stesso tier.

Il comportamento dipende dalla durata:

Durata diversa → Si comporta come un downgrade

• Effettivo alla prossima data di rinnovo
• Esempio: Premium mensile (livello 1) → Premium annuale (livello 1)

Stessa durata → Si comporta come un aggiorna

• Ha effetto immediato
• Esempio: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)

Creare un Subscription Group

1. Vai su Subscriptions

   In App Store Connect, seleziona la tua app e vai su Monetizzazione > Abbonamenti.

2. Crea Gruppo

   Clicca su + accanto a “Subscription Groups” per creare un nuovo gruppo.

3. Dai un nome al gruppo

   Scegli un nome descrittivo che rifletta gli abbonamenti inclusi:

   • “Accesso Premium”
   • “Piani di Cloud Storage”
   • “Funzionalità Pro”

4. Aggiungi abbonamenti

   Dopo aver creato il gruppo, aggiungi i singoli abbonamenti. Ogni abbonamento avrà un livello di ranking.

5. Imposta il ranking dei livelli

   Ordina gli abbonamenti dal valore più alto (1) al più basso. Considera che:

   • Annual plans typically rank higher than monthly
   • I piani con prezzo più alto hanno priorità su quelli meno costosi
   • Ultimate/premium tiers rank highest

Utilizzo nell'app

Il plugin native-purchases gestisce automaticamente la logica dei gruppi 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 agli utenti

Comunica sempre in modo chiaro il comportamento delle modifiche:

Per gli Upgrade:

“Avrai accesso immediato alle funzioni Premium. Il costo del tuo abbonamento attuale verrà riproporzionato.”

Per i Downgrade:

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

Per i Crossgrade:

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

Monitoraggio lato server

Usa le App Store Server Notifications v2 di Apple o il tuo backend di validazione degli scontrini per riflettere i cambiamenti di StoreKit nel tuo database. Abbina le notifiche server al transactionUpdated listener, così client e backend rimarranno sempre sincronizzati.

Best practice

Organizzazione dei gruppi

• Mantieni gli abbonamenti correlati nello stesso gruppo
• Non mischiare funzionalità non correlate (es. storage e rimozione della pubblicità)
• Crea gruppi separati per set di funzionalità diversi

Strategia di ranking dei livelli

• Piani annuali → Livello superiore rispetto ai mensili (stesso tier)
• Tier con prezzo più alto → Livello superiore
• Valuta il valore, non solo il prezzo

Esperienza utente

• Mostra chiaramente l'abbonamento attuale
• Visualizza tutte le opzioni disponibili nel gruppo
• Indica quali modifiche sono immediate o al rinnovo
• Permetti il passaggio rapido tra i piani

Test

• Testa tutti gli scenari di upgrade
• Testa tutti gli scenari di downgrade
• Verifica il comportamento del crossgrade
• Controlla l'invio dei 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)

• Basic → Premium: Upgrade (immediato)
• Premium → Ultimate: Upgrade (immediato)
• Ultimate → Premium: Downgrade (al rinnovo)
• Basic → Ultimate: Upgrade (immediato)

Scenario 2: piani a 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: multi-livello e 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 massima flessibilità mantenendo una logica di upgrade/downgrade chiara.

Risoluzione problemi

L'abbonamento non appare nel gruppo:

• Verifica che sia assegnato al gruppo corretto
• Controlla che sia almeno in stato “Ready to Submit”
• Assicurati che il product ID sia corretto

Comportamento upgrade/downgrade errato:

• Controlla i livelli di ranking (1 = il più alto)
• Verifica la coerenza dei tier di abbonamento
• Verifica che i livelli siano impostati correttamente

Prodotti provenienti da gruppi diversi:

• Gli utenti possono sottoscrivere più gruppi contemporaneamente
• È intenzionale: tieni i prodotti correlati nello stesso gruppo

getActiveProducts mostra più abbonamenti:

• Verifica se gli abbonamenti appartengono a gruppi diversi
• Verifica che l'utente non sia abbonato tramite Family Sharing
• Controlla lo stato degli abbonamenti in App Store Connect

Risorse aggiuntive

Per maggiori dettagli, consulta la documentazione ufficiale Apple sui gruppi di abbonamento.

Continua da «Crea gruppo di abbonamento iOS»

Se stai usando Crea gruppo di abbonamento iOS per pianificare l'approvazione e la distribuzione negli store, collegalo a Utilizzo di @capgo/native-purchases per la funzionalità nativa in Utilizzo di @capgo/native-purchases, @capgo/capacitor-in-app-review per i dettagli di implementazione in @capgo/capacitor-in-app-review, Utilizzo di @capgo/capacitor-in-app-review per la funzionalità nativa in Utilizzo di @capgo/capacitor-in-app-review, @capgo/capacitor-native-market per i dettagli di implementazione in @capgo/capacitor-native-market, e Utilizzo di @capgo/capacitor-native-market per la funzionalità nativa in Utilizzo di @capgo/capacitor-native-market.