Vai al contenuto

Crea gruppo di abbonamento iOS

GitHub

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.

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.

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

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:

Gerarchia del gruppo di abbonamento

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)

Apple gestisce automaticamente tre tipi di modifica dell'abbonamento in base alla classifica dei livelli:

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 time

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

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)
  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. Nome del gruppo

    Scegli un nome descrittivo che rifletta gli abbonamenti che contiene:

    • “Accesso Premium”
    • “Piani di archiviazione cloud”
    • “Funzionalità Pro”
  4. Aggiungi abbonamenti

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

  5. 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

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

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].”

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.

  • 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
  • Piani annuali → Livello superiore rispetto ai mensili (stesso tier)
  • Tier con prezzo più alto → Livello superiore
  • Valuta il valore, non solo il prezzo
  • 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
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)
Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)
  • Mensile → Annuale: Crossgrade (al rinnovo)
  • Annuale → Mensile: Downgrade (al rinnovo)
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.

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

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.