Crea un gruppo di abbonamento iOS

Le raccolte di abbonamenti sono essenziali per organizzare e gestire più livelli di abbonamento all'interno della tua app iOS. La comprensione di come funzionano è cruciale per l'implementazione della funzionalità di aggiornamento, downgrade e crossgrade.

Che cos'è una Raccolta di Abbonamenti?

Una raccolta di abbonamenti è 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 automaticamente la transizione.

Perché le Raccolte di Abbonamenti sono importanti

Le raccolte di abbonamenti consentono:

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

Niveaux di abbonamento

Ogni abbonamento all'interno di un gruppo 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 di abbonamento:

Esempi di livello

Livello 1 (Valore Massimo)

• Abbonamento Premium Annuale (99,99€/anno)
• Ultimo Mensile (19,99€/mese)

Livello 2 (Valore Medio)

• Abbonamento Standard Annuale (49,99€/anno)
• Premium Mensile (9,99€/mese)

Livello 3 (Valore Minimo)

• Abbonamento Base Annuale (29,99€/anno)
• Standard Mensile (4,99€/mese)

Tipi di Modifica Abbonamento

Apple gestisce automaticamente tre tipi di cambiamenti di sottoscrizione in base al livello di classifica:

1. Aggiornamento

Passare a una abbonamento di livello superiore (ad esempio, livello 2 → livello 1). Comportamento:

Ha effetto

• immediatamente L'utente riceve
• rimborso prorogato __CAPGO_KEEP_0__ per 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

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

Ha effetto alla

• prossima data di rinnovo per tempo residuo
• Utente mantiene la sottoscrizione corrente fino alla scadenza
• 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 tier.

Il comportamento dipende dalla durata:

Durata diversa → Si comporta come abbassamento

• Efficacia a partire dalla prossima data di rinnovo
• Esempio: Premium mensile (Livello 1) → Premium annuale (Livello 1)

Durata identica → Si comporta come aggiornamento

• Efficacia immediata
• Esempio: Premium mensile (Livello 1) → Ultimate mensile (Livello 1)

Creazione di un Gruppo di Abbonamenti

1. Naviga alle Abbonamenti

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

2. Crea Gruppo

   Clicca + Clicca sul pulsante successivo accanto a “Gruppi di Abbonamento” per creare un nuovo gruppo.

3. Nome il Gruppo

   Scegli un nome descrittivo che rifletta le abbonamenti che contiene:

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

4. Aggiungi Abbonamenti

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

5. Imposta Classificazioni di Livello

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

   • Piani annuali sono tipicamente classificati in alto rispetto a quelli mensili
   • Gli strati più costosi sono classificati sopra quelli meno costosi
   • Gli strati ultimate/premium sono classificati in alto

Utilizzo nell'App

Il plugin native-purchases gestisce automaticamente la logica del gruppo 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

Comunicare sempre il comportamento di modifica in modo chiaro:

Per Aggiornamenti:

“Avrai accesso immediato alle funzionalità Premium. Ti verrà prorata la tua sottoscrizione attuale.”

Per Riduzioni:

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

Per Cambiamenti di Piano:

“Il tuo piano cambierà a fatturazione annuale al prossimo rinnovo il [data].”

Monitoraggio del Server

Utilizza le notifiche del server di App Store v2 di Apple o il tuo backend di validazione di ricevuta per riflettere le modifiche di StoreKit nel tuo database. Unisci le notifiche del server con il transactionUpdated ascoltatore in modo che sia sincronizzato sia il client che il backend.

Pratiche Ottimali

Organizzazione del Gruppo

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

Strategia di Classificazione dei Livelli

• Piani annuali → Livello più alto di quelli mensili (per la stessa fascia di prezzo)
• Livelli più costosi → Livello più alto
• Considerare il valore, non solo il prezzo

Esperienza Utente

• Mostra la sottoscrizione corrente in modo chiaro
• Visualizza tutte le opzioni disponibili nel gruppo
• Indica quali cambiamenti sono immediati vs. a rinnovo
• Consenti di passare facilmente da un piano all'altro

Test

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

• Basic → Premium: Aggiorna (immediato)
• Premium → Ultimate: Aggiorna (immediato)
• Ultimate → Premium: Riduci (alla rinnovazione)
• Basic → 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-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 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 pubblicazione”
• Assicurati che l'ID del prodotto sia corretto

Comportamento di aggiornamento/abbassamento errato:

• Verifica i livelli di classifica (1 = più alto)
• Verifica che i livelli delle sottoscrizioni 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ù 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 rinvia alla documentazione ufficiale di Apple sulla gestione delle sottoscrizioni.

Continua da Creare un gruppo di sottoscrizione iOS

Se stai utilizzando Creare un gruppo di sottoscrizione iOS per pianificare l'approvazione e la distribuzione della store, connettilo con Utilizzare @capgo/native-purchases per la capacità nativa in Utilizzare @capgo/native-purchases, @capgo/capacitor-recensione in-app per il dettaglio di implementazione in @capgo/capacitor-recensione in-app, Utilizzare @capgo/capacitor-recensione in-app per la capacità nativa in Utilizzare @capgo/capacitor-recensione in-app, @capgo/capacitor-mercato nativo per il dettaglio di implementazione in @capgo/capacitor-mercato nativo, e Utilizzare @capgo/capacitor-mercato nativo per la capacità nativa in Utilizzare @capgo/capacitor-mercato nativo.