Configura il testing sandbox iOS

Per testare gli acquisti in-app su iOS è necessaria una configurazione corretta in App Store Connect e sui tuoi dispositivi di test. Questa guida copre tutto ciò che serve per iniziare con il sandbox testing.

Prerequisiti

• Apple Developer Program: Iscrizione attiva con rinnovo annuale
• Accordi: “Accordo per le app a pagamento” firmato con dati bancari e fiscali compilati
• Progetto Xcode: Configurato con bundle identifier e capabilities corretti

Nota

L'approvazione della configurazione bancaria e fiscale può richiedere da ore a giorni. Completala con largo anticipo rispetto ai test.

Processo di setup

1. Firma l’Accordo per le app a pagamento

   In App Store Connect, vai su Accordi, tasse e banca e completa:

   • Firma l'accordo per le app a pagamento
   • Aggiungi i dati bancari
   • Compila i moduli fiscali

   Attendi l'approvazione dei tuoi dati da parte di Apple (possono essere necessarie 24-48 ore).

2. Crea un utente Sandbox Test

   In App Store Connect, vai su Utenti e accesso > Sandbox Tester.

   Clicca sul + per creare un nuovo sandbox tester.

   Importante: Usa un indirizzo email che NON sia già associato a un Apple ID. Puoi usare gli alias email:

   • Gmail: youremail+test@gmail.com
   • iCloud: youremail+test@icloud.com

   

3. Configura il dispositivo di test (iOS 12+)

   A partire da iOS 12, non è più necessario uscire dal proprio account iTunes per testare gli acquisti.

   Sul tuo dispositivo iOS:

   1. Apri Impostazioni
   2. Tocca App Store
   3. Scorri fino in fondo
   4. Tocca Account Sandbox
   5. Accedi con il tuo account di test sandbox

   Tip

   È molto più comodo del vecchio metodo che richiedeva il logout dall'account iTunes!

4. Configura il progetto Xcode

   Assicurati che il tuo progetto Xcode abbia:

   Bundle Identifier

   • Deve corrispondere all'identificatore nel Developer Center
   • Deve corrispondere all'identificatore in App Store Connect

   Capability In-App Purchase

   1. Seleziona il tuo progetto in Xcode
   2. Vai su Firma e Capabilities
   3. Clicca su + Funzionalità
   4. Aggiungi Acquisti In-App

5. Crea i prodotti In-App Purchase

   In App Store Connect, vai alla tua app e crea i prodotti In-App Purchase (abbonamenti, consumabili, ecc.).

   Per il testing in sandbox, i prodotti devono avere almeno lo stato “Ready to Submit”.

6. Testa la tua implementazione

   Fai la build e avvia l'app su un dispositivo di test. Quando provi a effettuare un acquisto, dovresti vedere:

   [Ambiente: Sandbox]

   Questa conferma indica che ti trovi nell'ambiente sandbox e non ti verranno addebitati soldi reali.

Note importanti

Caratteristiche dell'ambiente Sandbox

• Nessun addebito reale: In modalità sandbox tutti gli acquisti sono gratuiti
• Abbonamenti accelerati: La durata degli abbonamenti è ridotta per test più rapidi
  • Abbonamento 1 settimana = 3 minuti
  • Abbonamento 1 mese = 5 minuti
  • Abbonamento 2 mesi = 10 minuti
  • Abbonamento 3 mesi = 15 minuti
  • Abbonamento 6 mesi = 30 minuti
  • Abbonamento 1 anno = 1 ora
• Limite rinnovo automatico: In sandbox, gli abbonamenti si rinnovano fino a 6 volte
• Cancellazione immediata: Gli abbonamenti cancellati scadono immediatamente

Gestione account Sandbox

• Crea più account di test per diversi scenari
• Usa gli account di test solo su dispositivi di test
• Non usare il tuo Apple ID personale per i test in sandbox
• Test accounts can purchase any product regardless of region

Utilizzo del testing Sandbox

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

const { isBillingSupported } = await NativePurchases.isBillingSupported();
if (!isBillingSupported) {
  throw new Error('StoreKit not supported on this device');
}

// Fetch products (automatically uses sandbox when available)
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Make test purchase
const transaction = await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_monthly',
  productType: PURCHASE_TYPE.SUBS,
});

console.log('Test purchase successful!', transaction.transactionId);

Verification

Una volta configurato correttamente, dovresti osservare:

1. Banner Sandbox durante l'acquisto: “[Environment: Sandbox]”
2. Caricamento prodotti con successo
3. Acquisti completati senza addebiti reali
4. Ricevute validate correttamente
5. Gli abbonamenti si rinnovano automaticamente (a velocità accelerata)

Risoluzione problemi

Prodotti non caricati:

• Verifica che il bundle identifier corrisponda ad App Store Connect
• Controlla che gli accordi siano firmati e approvati
• Assicurati che i prodotti siano almeno in stato “Ready to Submit”
• Attendi 2-3 ore dopo aver creato i prodotti

“Impossibile connettersi all'iTunes Store”:

• Verifica che l'account sandbox sia configurato correttamente
• Controlla che il dispositivo sia connesso a internet
• Prova a disconnetterti e rientrare nell'account sandbox
• Riavvia l'app

Gli acquisti falliscono in silenzio:

• Controlla la console di Xcode per i messaggi di errore
• Verifica che la capability In-App Purchase sia abilitata
• Assicurati che l'email dell'account sandbox non sia un Apple ID reale
• Prova a creare un nuovo account di test sandbox

Errori di validazione della ricevuta:

• Usa l'endpoint di validazione ricevute sandbox in fase di test
• Endpoint di produzione: https://buy.itunes.apple.com/verifyReceipt
• Endpoint sandbox: https://sandbox.itunes.apple.com/verifyReceipt
• Il plugin native-purchases lo gestisce automaticamente

Durata dell'abbonamento errata:

• Ricorda che in sandbox gli abbonamenti sono accelerati
• Usa la tabella di conversione sopra per le durate previste
• In sandbox gli abbonamenti si rinnovano automaticamente max 6 volte

“Questo Apple ID non è ancora stato usato nell'iTunes Store”:

• È normale per i nuovi account sandbox
• Procedi con l'acquisto per attivare l'account
• Accade solo al primo utilizzo

Best practice

1. Crea più account di test per diversi scenari di test
2. Testa tutte le durate degli abbonamenti per verificarne il comportamento
3. Testa i flussi di cancellazione e rinnovo
4. Verifica che la validazione delle ricevute funzioni correttamente
5. Testa la funzionalità di ripristino degli acquisti
6. Verifica l'upgrade/downgrade dell'abbonamento comportamento
7. Test con condizioni di rete scarse

Produzione vs Sandbox

Funzionalità	Sandbox	Produzione
Addebiti reali	No	Sì
Durata dell'abbonamento	Accelerato	Normale
Limite rinnovo automatico	6 volte	Illimitato
Effetto cancellazione	Immediata	Fine periodo
Endpoint ricevuta	URL Sandbox	URL Produzione
Solo account di test	Sì	No

Risorse aggiuntive

Per maggiori dettagli, consulta la documentazione ufficiale Apple StoreKit sul testing in sandbox.

Continua da Configura il testing Sandbox iOS

Se stai usando Configura il testing sandbox 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.