Creare Gruppo di Abbonamento iOS

I gruppi di abbonamento sono essenziali per organizzare e gestire più livelli di abbonamento nella tua app iOS. Comprendere come funzionano è cruciale per l'implementazione della funzionalità di aggiornamento, downgrade e crossgrade.

Cos'è un Gruppo di Abbonamento?

Un gruppo di abbonamento è una raccolta di abbonamenti correlati che gli utenti possono scegliere tra loro. Gli utenti possono abbonarsi solo a un abbonamento all'interno di un gruppo alla volta. Quando passano da un abbonamento all'altro, Apple gestisce automaticamente la transizione.

Perché i Gruppi di Abbonamento sono importanti

Gruppi di abbonamento abilitano:

• Pianificazione a più livelli: Offri piani base, premium e ultimate
• Diversi periodi: Opzioni mensili, annuali e a vita
• Logica di aggiornamento/abbassamento: Gestione automatica delle modifiche degli abbonamenti
• Gestione semplificata: Raggruppa gli abbonamenti correlati

Niveletti di abbonamento

Entro un gruppo, ogni abbonamento dovrebbe essere classificato in base al suo valore, partendo dal più alto (livello 1) e scendendo fino al più basso. Questa classificazione determina come vengono classificate le modifiche degli abbonamenti:

Esempi di livello

Livello 1 (Valore più alto)

• Annuale Premium ($99,99/all'anno)
• Mensile Premium ($19,99/mese)

Livello 2 (Valore medio)

• Annuale Standard ($49,99/all'anno)
• Mensile Premium ($9,99/mese)

Livello 3 __CAPGO_KEEP_0__

• Piano Base Annuale ($29,99/anno)
• Rinnovo Mensile Base ($4,99/mese)

Tipi di Modifica Abbonamento

Apple gestisce automaticamente tre tipi di modifiche degli abbonamenti in base al livello di classifica:

1. Aggiornamento

Passare a un livello di abbonamento più alto (ad esempio, livello 2 → livello 1). Comportamento:

1. Aggiornamento

• Ha effetto immediatamente
• L'utente riceve un 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. Downgrade

Passare a un livello inferiore subscription (ad esempio, livello 1 → livello 2).

Comportamento:

• Ha effetto a data di rinnovo successiva
• L'utente mantiene la corrente sottoscrizione fino a fine 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. Crossgrade

Passaggio a un'altra sottoscrizione al medesimo livello di categoria.

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 elevamento

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

Creazione di un Gruppo di Abbonamento

1. Naviga a Abbonamenti

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

2. Crea Gruppo

   Clicca + a lato di “Gruppi di Abbonamento” 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”
   • “Caratteristiche Pro”

4. Aggiungi Abbonamenti

   Dopo aver creato il gruppo, aggiungi abbonamenti individuali a esso. Ogni abbonamento avrà un livello di classifica.

5. Imposta Classifiche di Livello

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

   • I piani annuali sono tipicamente classificati più in alto rispetto a quelli mensili
   • I livelli più costosi si collocano sopra quelli meno costosi
   • I livelli ultimate/premium sono classificati più in alto

Utilizzo nel Tuo App

Il plugin di acquisti nativi 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 dei Cambiamenti di Abbonamento

Rilevamento 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 all'Utente

Comunica sempre il comportamento del cambio in modo chiaro:

Per Aggiornamenti:

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

Per Riduzioni:

“Avrai accesso Premium fino a [data di rinnovo], poi passerai a Standard.”

Per Cambiamenti di Categoria:

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

Monitoraggio del server

Utilizza le notifiche del server di App Store di Apple v2 o il tuo backend di validazione di ricevuta per riflettere le modifiche di StoreKit nel tuo database. Abbinare le notifiche del server con il transactionUpdated listener

in modo che sia sincronizzato sia il client che il backend.

Sezione intitolata “Pratiche raccomandate”

• Sezione intitolata “Organizzazione dei gruppi”
• Tenere le sottoscrizioni correlate nello stesso gruppo
• Non mescolare funzionalità non correlate (ad esempio, archiviazione e rimozione degli annunci pubblicitari).

Schema di Classificazione dei Livelli

• Piani annuali → Livello superiore rispetto a mensili (per stesso livello)
• Livelli più costosi → Livello superiore
• Considerare 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

• Testare tutti gli scenari di aggiornamento
• Testare tutti gli scenari di downgrade
• Verificare il comportamento di crossgrade
• Controllare l'invio di 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)
• Ultimo → Premium: Riduzione (al rinnovo)
• Base → Ultimo: Aggiornamento (immediato)

Scenario 2: Piani di durata misti

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

• Mensile → Annuale: Miglioramento (al rinnovo)
• Annuale → Mensile: Riduzione (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/riduzione chiara.

Risoluzione dei problemi

La sottoscrizione non compare nel gruppo:

• Verifica che sia assegnata al gruppo corretto
• Controlla che sia in almeno lo stato “Pronto per la pubblicazione”
• Assicurati che l’ID del prodotto sia corretto

Comportamento di aggiornamento/riduzione errato:

• Verifica le classifiche dei livelli (1 = più alto)
• Verifica che le fasce di sottoscrizione siano coerenti
• Controlla 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ù sottoscrizioni:

• Controlla se le sottoscrizioni sono in gruppi diversi
• Verifica che l'utente non sia sottoscritto tramite Family Sharing
• Verifica lo stato della sottoscrizione in App Store Connect

Risorse aggiuntive

Per ulteriori informazioni, si riferisca alla documentazione ufficiale di Apple sui gruppi di sottoscrizione.

Continua da Creare Gruppo di Sottoscrizione iOS

Se stai utilizzando Creare Gruppo di Sottoscrizione iOS per pianificare l'approvazione e la distribuzione del negozio, connettilo con Usando @capgo/native-purchases per la capacità nativa in Usando @capgo/native-purchases, @capgo/capacitor-in-app-review per il dettaglio di implementazione in @capgo/capacitor-in-app-review, Usando @capgo/capacitor-in-app-review per la capacità nativa in Usando @capgo/capacitor-in-app-review, @capgo/capacitor-native-market per il dettaglio di implementazione in @capgo/capacitor-native-market, e Usando @capgo/capacitor-native-market per la capacità nativa in Usando @capgo/capacitor-native-market.