Creare gruppo di 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 implementare la funzionalità di aggiornamento, riduzione e crossgrade.

Cosa è 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

I gruppi di abbonamento consentono:

• Prezzi a schiera: Offrire piani base, premium e ultimate
• Diversi periodi di durata: Opzioni mensili, annuali e a vita
• Logica di aggiornamento/abbassamento: Gestione automatica delle modifiche degli abbonamenti
• Gestione semplificata: Raggruppare insieme le relative abbonamenti

Livelli di Abbonamento

Ogni abbonamento all'interno di un gruppo dovrebbe essere classificato in base al suo valore (livello 1) più alto a quello più basso. Questa classificazione determina come le modifiche agli abbonamenti vengono classificate:

Livelli di esempio

Livello 1 (Valore più alto)

• Premium annuale (99,99€/anno)
• Ultimo mese (19,99€/mese)

Livello 2 (Valore medio)

• Standard annuale (49,99€/anno)
• Premium Mensile ($9.99/mese)

Nivel 3 (Valore più basso)

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

Tipi di Modifica della Sottoscrizione

L'Apple gestisce automaticamente tre tipi di modifiche della sottoscrizione in base alla classificazione del livello:

1. Aggiornamento

Passare a un livello superiore sottoscrizione (ad esempio, livello 2 → livello 1).

Comportamento:

• Ha effetto immediatamente
• L'utente riceve rimborso prorogato 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 piano di abbonamento inferiore (ad esempio, livello 1 → livello 2). Livello di abbonamento inferiore Comportamento:

Ha effetto alla data di rinnovo successiva

• L'utente mantiene l'attuale abbonamento fino alla fine del periodo L'abbonamento nuovo inizia automaticamente dopo la scadenza
• Esempio:
• Copia negli appunti

3. Crossgrade

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

Takes effect at __CAPGO_KEEP_0__ next renewal date

Passaggio a un'altra sottoscrizione allo stesso livello di tariffa.

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)

Stessa durata → Si comporta come elevazione

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

Crea 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 + il pulsante ‘+’ accanto a ‘Gruppi di Abbonamento’ per creare un nuovo gruppo.

3. Dai un Nome al 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 classificazione.

5. Imposta Classificazioni di Livello

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

   • I piani annuali solitamente hanno un livello di classificazione più alto rispetto a quelli mensili
   • I livelli più costosi si collocano sopra quelli meno costosi
   • I livelli ultimate/premium hanno il livello di classificazione più alto

Utilizzo nell'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 del tipo di modifica

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 con l'utente

Comunica sempre il comportamento di modifica in modo chiaro:

Per gli aggiornamenti:

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

Per le riduzioni di livello:

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

Per Crossgrades:

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

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 Pratiche raccomandate

Sezione intitolata “Pratiche raccomandate”

Sezione intitolata “Organizzazione dei gruppi”

• For Crossgrades:__CAPGO_KEEP_0__
• Non mescolare funzionalità non correlate (ad esempio, archiviazione e rimozione degli annunci)
• Creare gruppi separati per set di funzionalità diversi

Strategia di Classificazione dei Livelli

• Piani annuali → Livello superiore rispetto ai mensili (per stesso livello)
• Livelli più costosi → Livello superiore
• Considerare il valore, non solo il prezzo

Esperienza Utente

• Mostrare la sottoscrizione corrente in modo chiaro
• Visualizzare tutte le opzioni disponibili nel gruppo
• Indicare 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 riduzione
• Verificare il comportamento di crossgrade
• Controllare 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)

• Basic → Premium: Aggiorna (immediato)
• Premium → Ultimate: Aggiorna (immediato)
• Ultimate → Premium: Riduci (alla rinnovazione)
• Basic → Ultimate: Aggiorna (immediato)

Scenario 2: Piani di durata misti

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

• Monthly → Annual: Migliora (alla rinnovazione)
• Annual → Monthly: Riduci (alla rinnovazione)

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/scostamento chiara.

Risoluzione dei problemi

Abbonamento non presente nel gruppo:

• Verifica che sia assegnato 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/scostamento sbagliato:

• Verifica che i livelli di classifica siano corretti (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 - tenere i prodotti correlati nello stesso gruppo

getActiveProducts che 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 prega di consultare il documentazione ufficiale di Apple sui gruppi di sottoscrizione.

Continua da Creare Gruppo di Sottoscrizione iOS

If sei stai utilizzando Crea un gruppo di abbonamento iOS per pianificare l'approvazione e la distribuzione della store, collega Utilizza @capgo/native-purchases per la capacità nativa in Utilizza @capgo/native-purchases, @capgo/capacitor-in-app-review per il dettaglio di implementazione in @capgo/capacitor-in-app-review, Utilizza @capgo/capacitor-in-app-review per la capacità nativa in Utilizza @capgo/capacitor-in-app-review, @capgo/capacitor-native-market per il dettaglio di implementazione in @capgo/capacitor-native-market, e Utilizza @capgo/capacitor-native-market per la capacità nativa in Utilizzo di @capgo/capacitor-native-market.