Creare Gruppo Abbonamento iOS

I gruppi di abbonamento sono essenziali per organizzare e gestire più livelli di abbonamento nella tua app iOS. Capire 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 cambiano abbonamento, Apple gestisce la transizione automaticamente.

Perché i Gruppi di Abbonamento sono importanti

I gruppi di abbonamento consentono:

• Prezzi a livelli: Offri piani base, premium e ultimate
• Diversi periodi: Opzioni mensili, annuali e a vita
• Logica di aggiornamento/abbassamentoGestione automatica delle modifiche di abbonamento
• Gestione semplificata: Gestione di abbonamenti correlati

Livelli di Abbonamento

All'interno di 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 sono classificate le modifiche di abbonamento:

Esempi di Livello

Livello 1 (Valore più alto)

• Premium Annual ($99.99/year)
• Ultimo Mensile Premium ($9.99/mese)

Livello 2 (Valore medio)

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

Livello 3 (Valore più basso)

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

Tipi di Modifica della Sottoscrizione

Apple gestisce automaticamente tre tipi di modifiche delle sottoscrizioni in base al livello di classifica:

1. Aggiornamento

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

Ha effetto

• immediatamente L'utente riceve
• un rimborso parziale per il tempo residuo __CAPGO_KEEP_0__
• 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

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

Ha effetto alla

• data di rinnovo successiva L'utente mantiene la sottoscrizione corrente fino alla scadenza del periodo.
• __CAPGO_KEEP_0__
• 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 allo stesso livello di tier.

Il comportamento dipende dalla durata:

Diversa Durata → Si comporta come abbassamento

• Ha effetto alla data di rinnovo successiva
• Esempio: Abbonamento mensile (Livello 1) → Abbonamento annuale (Livello 1)

Durata uguale → Si comporta come aggiornamento

• Ha effetto immediatamente
• Esempio: Abbonamento mensile (Livello 1) → Abbonamento mensile Ultimate (Livello 1)

Creare un Gruppo di Abbonamento

1. Naviga alle Abbonamenti

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

2. Crea Gruppo

   Clicca + vicino a “Gruppi di Abbonamento” per creare un nuovo gruppo.

3. Nome del Gruppo

   Scegli un nome descrittivo che rifletta le sottoscrizioni che contiene:

   • “Accesso Premium”
   • “Piani di Archiviazione Cloud”
   • “Caratteristiche Pro”

4. Aggiungi Sottoscrizioni

   Dopo aver creato il gruppo, aggiungi le sottoscrizioni individuali a esso. Ogni sottoscrizione avrà un livello di classificazione.

5. Imposta Livelli di Classificazione

   Ordina le sottoscrizioni dal valore più alto (1) al valore più basso. Considera:

   • I piani annuali solitamente hanno un valore più alto rispetto ai piani mensili.
   • Le fasce tariffarie più costose si collocano sopra quelle meno costose
   • Le fasce tariffarie ultimate/premiative si collocano più in alto

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 dei Cambiamenti di Abbonamento

Rilevamento del 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 Utente

Comunica sempre il comportamento di modifica in modo chiaro:

Per gli Aggiornamenti:

“Avrai accesso immediato alle funzionalità Premium. Ti rimborsiamo la tua sottoscrizione corrente.”

Per le Riduzioni:

“Mantieni l'accesso Premium fino alla [data di rinnovo], poi passa a Standard.”

Per le Crossgrade:

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

Monitoraggio del server

Utilizza le notifiche del server di Apple Store Server Notifications v2 o il tuo backend di validazione di ricevuta per riflettere le modifiche di StoreKit nel tuo database. Abbinare le notifiche del server con l'ascoltatore per mantenere sincronizzati sia il client che il backend. transactionUpdated Utilizza le notifiche del server di Apple Store Server Notifications v2 o il tuo backend di validazione di ricevuta per riflettere le modifiche di StoreKit nel tuo database. Abbinare le notifiche del server con l'ascoltatore per mantenere sincronizzati sia il client che il backend.

Pratiche Migliori

Organizzazione del Gruppo

• Mantieni le sottoscrizioni correlate nello stesso gruppo
• Non mescolare funzionalità non correlate (ad esempio, archiviazione e rimozione pubblicità)
• Crea gruppi separati per insiemi di funzionalità diversi

Strategia di Classificazione dei Livelli

• Piani annuali → Livello più alto dei piani mensili (per stesso livello)
• Livelli più costosi → Livello più alto
• Considera il valore, non solo il prezzo

Esperienza Utente

• Mostra chiaramente la sottoscrizione corrente
• Visualizza tutte le opzioni disponibili nel gruppo
• Indica quali cambiamenti sono immediati vs. a rinnovo
• Consenti un facile spostamento tra piani

Test

• Testa tutti gli scenari di aggiornamento
• Testa tutti gli scenari di riduzione
• Verifica il comportamento di crossgrade
• Controlla l'invio 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)

• Di base → Premium: Aggiorna (immediato)
• Premium → Ultimate: Aggiorna (immediato)
• Ultimate → Premium: Riduci (alla rinnovazione)
• Di base → Ultimate: Aggiorna (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: 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 fornisce la massima flessibilità mantenendo una logica di aggiornamento/scadenzamento 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 presentazione”
• Assicurati che l'ID del prodotto sia corretto

Comportamento di aggiornamento/riduzione errato:

• Livelli di valutazione (1 = più alto)
• Verifica che i livelli di abbonamento siano sensati
• Controlla che i livelli siano impostati correttamente

Prodotti da gruppi diversi:

• Gli utenti possono sottoscrivere a più gruppi contemporaneamente
• Questo è intenzionale - mantenere i prodotti correlati nello stesso gruppo

getActiveProducts mostra più abbonamenti:

• Controlla se gli abbonamenti sono in gruppi diversi
• Verifica che l'utente non sia sottoscritto tramite Family Sharing
• Verifica lo stato di abbonamento in App Store Connect

Risorse aggiuntive

Per ulteriori informazioni, si prega di consultare la 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 della tua app, collega 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.