Crea gruppo di abbonamento iOS
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
I gruppi di abbonamenti sono essenziali per organizzare e gestire più livelli di abbonamento nella tua app iOS. Capire come funzionano è fondamentale per implementare le funzionalità di upgrade, downgrade e crossgrade.
Che cos'è un gruppo di abbonamenti?
Sezione intitolata “Che cos'è un gruppo di abbonamenti?”Un gruppo di abbonamenti è un insieme di abbonamenti correlati tra cui gli utenti possono scegliere. Un utente può sottoscrivere un solo abbonamento all'interno di un gruppo alla volta. Quando cambia abbonamento, Apple gestisce la transizione automaticamente.
Perché i gruppi di abbonamenti sono importanti
Sezione intitolata “Perché i gruppi di abbonamenti sono importanti”I gruppi di abbonamenti consentono:
- Prezzi a livelli: Offrire 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 gli abbonamenti correlati
Livelli di abbonamento
Sezione intitolata “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 cambi di abbonamento:

Esempi di livelli
Sezione intitolata “Esempi di livello”Livello 1 (Valore più alto)
- Premium Annual ($99.99/anno)
- Ultimate Monthly ($19,99/mese)
Livello 2 (Valore medio)
- Standard Annual ($49,99/anno)
- Premium Monthly ($9,99/mese)
Livello 3 (Valore minimo)
- Basic Annual ($29,99/anno)
- Standard Monthly ($4,99/mese)
Tipi di cambio abbonamento
Sezione intitolata “Tipi di modifica dell'abbonamento”Apple gestisce automaticamente tre tipi di modifica dell'abbonamento in base alla classifica dei livelli:
1. Aggiorna
Sezione intitolata “1. Upgrade”Passaggio a un tier superiore 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 time2. Downgrade
Sezione intitolata “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 switches3. Crossgrade
Sezione intitolata “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 upgrade
- Ha effetto immediato
- Esempio: Premium Monthly (Level 1) → Ultimate Monthly (Level 1)
Creare un Subscription Group
Sezione intitolata “Creare un Subscription Group”-
Vai su Subscriptions
In App Store Connect, seleziona la tua app e vai su Monetizzazione > Abbonamenti.
-
Crea Gruppo
Clicca su + accanto a “Subscription Groups” per creare un nuovo gruppo.
-
Nome del gruppo
Scegli un nome descrittivo che rifletta gli abbonamenti che contiene:
- “Accesso Premium”
- “Piani di archiviazione cloud”
- “Funzionalità Pro”
-
Aggiungi abbonamenti
Dopo aver creato il gruppo, aggiungi i singoli abbonamenti. Ogni abbonamento avrà un livello di ranking.
-
Imposta i livelli di ranking
Ordina gli abbonamenti dal valore più alto (1) al più basso. Considera:
- Annual plans typically rank higher than monthly
- Le fasce di prezzo più alte hanno priorità rispetto a quelle più basse
- I livelli Ultimate/premium hanno la priorità massima
Utilizzo nell'app
Sezione: “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 groupconst { products } = await NativePurchases.getProducts({ productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'], productType: PURCHASE_TYPE.SUBS,});
// Display current subscription using StoreKit transactionsconst { 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
Sezione intitolata “Gestione delle modifiche all'abbonamento”Rilevamento del tipo di modifica
Sezione intitolata “Rilevamento del tipo di modifica”import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
// Get current subscription infoconst { 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/downgradesNativePurchases.addListener('transactionUpdated', (transaction) => { console.log('Subscription changed!', transaction); if (transaction.subscriptionState === 'revoked') { revokeAccess(); } else if (transaction.isActive) { unlockPremiumFeatures(); }});Comunicazione agli utenti
Sezione intitolata “Comunicazione con l'utente”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
Sezione intitolata “Monitoraggio server”Usa le App Store Server Notifications v2 di Apple o il tuo backend di validazione delle ricevute per rispecchiare nel database le modifiche di StoreKit. Abbina le notifiche server al transactionUpdated listener, così client e backend restano sincronizzati.
Best practice
Sezione “Best practice”Organizzazione dei gruppi
Sezione intitolata “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
Sezione intitolata “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
Sezione intitolata “Esperienza utente”- Mostra chiaramente l’abbonamento attuale
- Mostra tutte le opzioni disponibili nel gruppo
- Indica quali modifiche sono immediate e quali al rinnovo
- Consenti di cambiare facilmente piano
- Testa tutti gli scenari di upgrade
- Testa tutti gli scenari di downgrade
- Verifica il comportamento del crossgrade
- Verifica l'invio del webhook
Scenari comuni
Sezione intitolata “Scenari comuni”Scenario 1: piani mensili a tre livelli
Sezione intitolata “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
Sezione intitolata “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
Sezione intitolata “Scenario 3: Multi-Tier Multi-Duration”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 chiara di upgrade/downgrade.
Risoluzione problemi
Sezione intitolata “Troubleshooting”L'abbonamento non compare nel gruppo:
- Verifica che sia assegnato al gruppo corretto
- Controlla che sia almeno in stato “Ready to Submit”
- Assicurati che l'ID prodotto sia corretto
Comportamento di upgrade/downgrade errato:
- Rivedi la gerarchia dei livelli (1 = più alto)
- Verifica che i livelli di abbonamento abbiano senso
- Verifica che i livelli siano impostati correttamente
Prodotti di gruppi diversi:
- Gli utenti possono abbonarsi a più gruppi contemporaneamente
- È intenzionale: mantieni i prodotti correlati nello stesso gruppo
getActiveProducts mostra più abbonamenti:
- Controlla se gli abbonamenti appartengono a gruppi diversi
- Verifica che l'utente non sia abbonato tramite Family Sharing
- Rivedi lo stato dell'abbonamento in App Store Connect
Risorse aggiuntive
Sezione “Risorse aggiuntive”Per maggiori dettagli, consulta la documentazione ufficiale Apple sui gruppi di abbonamento.
Continua da «Crea gruppo di abbonamento iOS»
Sezione intitolata “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.