Configura il Test di Sandbox per iOS

Per testare le compravendite in-app su iOS è necessaria una configurazione corretta in App Store Connect e sui dispositivi di test. Questa guida copre tutto ciò di cui hai bisogno per iniziare con il testing del sandbox.

Requisiti

• Programma di sviluppo Apple: Iscrizione attiva con rinnovo annuale
• Accordi: Accordo firmato “Paid Applications Agreement” con informazioni bancarie e fiscali completate
• Progetto Xcode: Configurato con identificatore di bundle e capacità corretti

Nota

La validazione delle impostazioni bancarie e fiscali può richiedere ore o giorni. Assicurati di completarla con anticipo rispetto alle prove.

Procedura di configurazione

1. Sottoscrivi l'Accordo per le Applicazioni a pagamento

   Nell'App Store Connect, naviga a Accordi, Tasse e Banche e completa:

   • Sottoscrivi l'Accordo per le Applicazioni a pagamento
   • Inserisci le tue informazioni bancarie
   • Completa i moduli fiscali

   Aspetta che Apple approvi le tue informazioni (questo può richiedere 24-48 ore).

2. Crea Utente di Test Sandbox

   In App Store Connect, vai a Utenti e Accesso > Testers di Sandbox.

   Clicca sul + tasto per creare un nuovo tester di sandbox.

   Importante: Utilizza un indirizzo email che NON è già associato a un ID Apple. Puoi utilizzare alias di posta elettronica:

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

   

3. Configura dispositivo di test (iOS 12+)

   A partire da iOS 12, non è più necessario disconnettersi dall'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

   Suggerimento

   Questa è molto più comoda rispetto al vecchio metodo di disconnessione del tuo account iTunes!

4. Configura Progetto Xcode

   Assicurati che il tuo progetto Xcode abbia:

   Identificatore Bundle

   • Deve corrispondere all'identificatore nel tuo Centro sviluppatori
   • Deve corrispondere all'identificatore in App Store Connect

   Funzionalità di acquisto in-app

   1. Seleziona il tuo progetto in Xcode
   2. Vai a Credenziali e Capacità
   3. Clicca + Funzionalità
   4. Aggiungi Acquisto in-app

5. Crea prodotti di acquisto in-app in App Store Connect

   In App Store Connect, naviga alla tua app e crea i tuoi prodotti di acquisto in-app (sottoscrizioni, consumabili, ecc.).

   I prodotti devono essere in almeno lo stato “Pronto per la pubblicazione” per il testing del sandbox.

6. Testa la tua implementazione

   Costruisci e esegui la tua app su un dispositivo di test. Quando tenti un acquisto, dovresti vedere:

   [Ambiente: Sandbox]

   Questa conferma indica che ti trovi nell'ambiente di testing del sandbox e non sarai addebitato denaro reale.

Nota importante

Caratteristiche dell'ambiente sandbox

• Nessuna tariffa realeTutti gli acquisti sono gratuiti in modalità sandbox
• Sottoscrizioni accelerateLe durate delle sottoscrizioni sono abbreviate per testare più velocemente
  • 1 settimana = 3 minuti
  • 1 mese = 5 minuti
  • 2 mesi = 10 minuti
  • 3 mesi = 15 minuti
  • 6 mesi = 30 minuti
  • 1 anno di abbonamento = 1 ora
• Limite di rinnovo automatico: Gli abbonamenti si rinnovano fino a 6 volte in sandbox
• Cancellazione immediata: Gli abbonamenti annullati scadono immediatamente

Gestione del conto di sandbox

• Crea conti di test multipli per scenari diversi
• Utilizza conti di test solo su dispositivi di test
• Non utilizzare un ID Apple personale per il testing di sandbox
• I conti di test possono acquistare qualsiasi prodotto indipendentemente dalla regione

Utilizzo del testing di 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);

Verifica

Quando configurato correttamente, dovresti osservare:

1. Banner del Sandbox durante l'acquisto: “Ambiente: Sandbox”
2. I prodotti si caricano con successo
3. Le transazioni si completano senza addebiti effettivi
4. Le ricevute si validano correttamente
5. Rinnovi delle sottoscrizioni automaticamente (a velocità accelerata)

Risoluzione dei problemi

Prodotti non caricati:

• Verifica che l'identificatore del bundle corrisponda a App Store Connect
• Assicurati che gli accordi siano firmati e approvati
• Assicurati che i prodotti siano almeno “Pronti per la pubblicazione”
• Attendi 2-3 ore dopo aver creato i prodotti

“Non è possibile connettersi al iTunes Store”:

• Verifica che l'account sandbox sia configurato correttamente
• Verifica che il dispositivo sia collegato a Internet
• Prova a disconnettersi e a riaccedere all'account sandbox
• Riavvia l'app

Acquisti che falliscono in silenzio:

• Controlla il console di Xcode per i messaggi di errore
• Verifica che la capacità di acquisto in-app sia abilitata
• Assicurati che l'indirizzo e-mail dell'account sandbox non sia un ID Apple reale
• Prova a creare un nuovo account di test sandbox

Errori di validazione del ricevuto:

• Utilizza l'endpoint di validazione del ricevuto sandbox durante le prove
• Endpoint di produzione: https://buy.itunes.apple.com/verifyReceipt
• Endpoint di sandbox: https://sandbox.itunes.apple.com/verifyReceipt
• Il plugin native-purchases gestisce automaticamente questo

Durata della sottoscrizione sbagliata:

• Ricorda che le sottoscrizioni sono accelerate nel sandbox
• Utilizza la tabella di conversione sopra per le durate previste
• Le sottoscrizioni si rinnovano automaticamente fino a 6 volte nel sandbox

“Questa Apple ID non è ancora stata utilizzata nell'iTunes Store”:

• Questo è normale per nuovi account sandbox
• Procedi con l'acquisto per attivare l'account
• Accade solo alla prima utilizzazione

Pratiche consigliate

1. Crea più account di prova per diverse scenari di test
2. Testare tutte le durate delle sottoscrizioni per verificare il comportamento
3. Testare annullamento e rinnovo delle sottoscrizioni flussi
4. Verificare la validazione della ricezione funziona correttamente
5. Testare il ripristino degli acquisti funzionalità
6. Verificare l'upgrade/downgrade della sottoscrizione comportamento
7. Testare con condizioni di rete scarse

Produzione vs. Sandbox

Funzione	Sandbox	Produzione
Carichi reali	No	Sì
Durata abbonamento	Accelerato	Normale
Limite di rinnovo automatico	6 volte	Senza limiti
Effetto di annullamento	In tempo reale	Fine del periodo
Punto di ricezione della ricevuta	URL del sandbox	URL di produzione
Solo per conti di test	Sì	No

Risorse aggiuntive

Per ulteriori informazioni, si riferisca al documentazione ufficiale di Apple StoreKit sui test di sandbox.