Retention Messaging API: il messaggio prima della disdetta

La Retention Messaging API è un servizio di Apple, da server a server, che mostra il tuo messaggio a un abbonato nel momento in cui tocca Cancel Subscription. Il messaggio compare in una pagina di conferma, prima che la disdetta venga confermata. Può ricordare il valore del tuo abbonamento, proporre un altro piano o un'offerta promozionale, ma il pulsante per disdire resta sempre lì. L'API è in anteprima da luglio 2025, su richiesta di accesso, e Apple ha annunciato una versione più semplice in App Store Connect per l'autunno 2026.

Questa guida spiega cosa mostra l'API, da quando esiste, chi può usarla, i suoi requisiti e come configurarla. Tutto viene dalla documentazione di Apple e dalla sessione WWDC26 dedicata, rilette il 3 novembre 2026.

Vendo abbonamenti nelle mie app iOS: Solys, un blocco per i social network, TradaZen, un simulatore di trading, Nolera, un'app per provare outfit con l'IA, e Vigie. Ho chiesto l'accesso all'API per tutte e quattro il 25 ottobre 2026 e ho preparato i loro messaggi in tutte le loro lingue. Il 28 ottobre l'approvazione di Apple non era ancora arrivata: questa guida descrive quindi la regola e la mia preparazione, non ancora dei risultati.

Cosa fa la Retention Messaging API

Secondo la documentazione di Apple, l'API ti permette di scegliere il messaggio che il sistema mostra quando un cliente apre la pagina di dettaglio di un abbonamento e forse sta per disdire. Prepari i messaggi in anticipo, per ogni prodotto e ogni lingua.

Il percorso è sempre lo stesso:

1. L'abbonato apre il suo abbonamento, per esempio da Apple Account, Subscriptions, oppure dall'App Store.
2. Tocca Cancel Subscription.
3. Il sistema mostra una pagina di conferma (Confirm Cancellation), con il tuo messaggio.
4. Può disdire comunque, tenere l'abbonamento o accettare quello che propone il tuo messaggio.

Il messaggio è visibile su iOS 15.1 e iPadOS 15.1 o successivi, su visionOS 1 e su macOS 14 o successivi.

Da quando, e per chi

Data	Cosa cambia, secondo Apple
16 lug. 2025	Versione 1.0: prima anteprima dell'API
9 dic. 2025	Test di prestazioni del server per il tempo reale
31 mar. 2026	Elenchi puntati nei messaggi, impostazione dell'indirizzo in tempo reale tramite API
27 apr. 2026	Supporto agli abbonamenti mensili con impegno di 12 mesi
Giugno 2026	WWDC26: annuncio di un modulo in App Store Connect

Le date vengono dal registro delle versioni dell'API, tranne l'ultima, presa dalla sessione WWDC26. L'API resta un'anteprima: la documentazione rimanda a un modulo di richiesta di accesso, che richiede il login al tuo account sviluppatore.

Alla WWDC26, la sessione Explore Retention Messaging in App Store Connect presenta un modulo configurabile senza codice, in App Store Connect. Apple lo definisce "aperto a tutti". La versione in tempo reale, invece, resta su richiesta. La pagina delle novità dell'App Store annuncia il modulo per "quest'autunno". Al 3 novembre 2026, la guida di App Store Connect non gli dedica ancora nessuna pagina, e il 28 ottobre il modulo non compariva nel mio account.

L'API riguarda le app che vendono un abbonamento con rinnovo automatico. Non è riservata ai grandi publisher: RevenueCat nota nel suo studio su 22 milioni di messaggi che anche le piccole app possono chiedere l'accesso.

I 4 tipi di messaggio

Tipo	Cosa vede l'abbonato	Messaggio predefinito	Tempo reale
Testo	Un titolo, un testo, fino a cinque punti elenco	Sì	Sì
Testo con immagine	La stessa cosa, con un'immagine	Sì	Sì
Cambio di piano	Un testo e un altro abbonamento dello stesso gruppo	No	Sì
Offerta promozionale	Un testo e un'offerta per continuare a prezzo ridotto	No	Sì

Secondo la pagina sulla preparazione dei messaggi, un messaggio predefinito può essere solo un testo, con o senza immagine. Con l'API, proporre un'offerta o un altro piano richiede di rispondere in tempo reale. Il modulo annunciato in App Store Connect offrirà invece un messaggio con un'offerta, senza server.

L'offerta promozionale è quella che crei in App Store Connect. Secondo la guida sulle offerte promozionali, si rivolge agli abbonati attuali ed ex abbonati. In un messaggio di retention è il tuo server a firmarla, secondo la pagina sulla preparazione dei messaggi. Il cambio di piano propone un abbonamento dello stesso gruppo. Se sei alle prime armi con queste offerte, leggi prima la mia guida sui codici offerta e le offerte promozionali.

Cosa puoi mostrare: i limiti esatti

Elemento	Limite di Apple
Titolo	Massimo 66 caratteri
Testo	Massimo 144 caratteri
Punti elenco	Massimo 5
Immagine a larghezza piena	PNG senza trasparenza, 3.840 px di larghezza, da 160 a 2.160 di altezza
Immagine del punto elenco	1.024 × 1.024 px
Immagini per app	Massimo 2.000

Le lunghezze vengono dalla descrizione del corpo della richiesta di invio di un messaggio, e i formati dalla pagina sull'invio di un'immagine. Apple chiede anche immagini che funzionino bene sia in modalità chiara sia in modalità scura.

Ogni messaggio e ogni immagine vengono revisionati da Apple. Il loro stato passa da PENDING ad APPROVED, e il sistema mostra solo ciò che è approvato. In sandbox l'approvazione è automatica. La documentazione pone una regola chiara sui contenuti: non inviare nulla di ingannevole o inesatto.

I requisiti da rispettare

• Un messaggio predefinito per ogni prodotto, in ogni lingua. Senza, in quella lingua non viene mostrato nulla. È anche la ruota di scorta se il tuo server non risponde.
• Messaggi e immagini approvati prima di qualsiasi pubblicazione.
• Per il tempo reale, un server veloce. La pagina sulla configurazione dell'indirizzo in tempo reale richiede un certificato SSL valido, TLS 1.2 e una risposta in meno di 700 ms in produzione. Oltre, la richiesta fallisce e viene mostrato il messaggio predefinito.
• Un test di prestazioni superato in sandbox, prima di registrare il tuo indirizzo di produzione.
• Una verifica dell'app. Ogni richiesta di Apple contiene l'identificativo dell'app, appAppleId. Se non corrisponde al tuo, Apple chiede di non rispondere.

La richiesta in tempo reale ti fornisce l'identificativo della transazione originale, il prodotto e la lingua del dispositivo. Sta a te scegliere il messaggio, secondo le tue regole.

Configurare la Retention Messaging: tre strade

Strada	Per chi	Cosa serve
Modulo App Store Connect	Tutti, una volta disponibile	Nessun codice; testo, immagine o offerta
API, con il tuo server	Chi ha un back-end	Accesso Apple, indirizzo HTTPS, test di prestazioni
API, tramite RevenueCat	Le app già su RevenueCat	Accesso Apple, impostazioni nella dashboard

Quando coesistono più configurazioni, nella sessione WWDC26 Apple spiega l'ordine seguito: prima la risposta in tempo reale. Se manca o è malformata, l'impostazione di App Store Connect. Se non esiste, il messaggio predefinito configurato tramite API.

Con il tuo server

1. Chiedi l'accesso con il modulo di Apple.
2. Invia le immagini, poi i messaggi, con un titolo e un testo per ciascuno.
3. Aspetta la loro approvazione, poi registra un messaggio predefinito per ogni abbonamento e ogni lingua.
4. Per il tempo reale, crea l'indirizzo Get Retention Message sul tuo server e registralo in sandbox.
5. Avvia il test di prestazioni, in sandbox, con una transazione di test.
6. Una volta superato il test, registra il tuo indirizzo di produzione.

Con RevenueCat

È la strada che ho scelto io: nessun server da scrivere, e le mie app passano già da RevenueCat, come spiego in RevenueCat e l'abbonamento in-app iOS. Secondo la documentazione di RevenueCat:

1. Nel modulo di Apple, l'indirizzo da indicare è quello che RevenueCat mostra nelle impostazioni della tua app App Store.
2. Dopo l'approvazione, apri Lifecycle, poi Retention, e collega l'indirizzo sandbox.
3. Avvia il test di prestazioni con un abbonamento sandbox o TestFlight attivo. Può durare fino a un'ora.
4. Crea prima un messaggio predefinito, lingua per lingua.
5. Aggiungi poi i messaggi in tempo reale, con delle regole. Una di queste, "Is in free trial", si rivolge a chi è in prova gratuita.
6. Passa in produzione: le impostazioni della sandbox non vengono riprese, bisogna ricreare i messaggi.

Scrivere un messaggio che trattiene senza ingannare

Il testo è fisso e viene revisionato da Apple prima di essere mostrato. Quindi non può parlare della persona che lo legge, né del giorno in cui lo legge. Ecco il messaggio predefinito che ho preparato per TradaZen, nella versione italiana:

Titolo (56 caratteri):
Volevi imparare a fare trading e ora riparti alla cieca?

Testo (134 caratteri):
Senza allenamento, i tuoi soldi veri pagano ogni errore. Qui non costano nulla. La tua serie, la tua lega e le tue lezioni si fermano.

Le regole che mi sono dato per le mie quattro app:

• Il titolo riporta la persona al suo obiettivo, sotto forma di domanda. Non la fa vergognare.
• Il testo dice cosa si ferma, esattamente. Scrivo che l'accesso "si blocca" quando i dati restano, mai che verranno "eliminati".
• Nessuna parola legata al tempo come "domani" o "oggi": lo stesso testo viene mostrato in qualsiasi momento del periodo.
• Nessuna promessa di guadagno, nessuna falsa urgenza. Un primo titolo che prometteva di cambiare vita grazie al trading è stato scartato prima dell'invio. La guideline 5.6 vieta qualsiasi pratica manipolatoria, e il paywall di TradaZen è già stato rifiutato per questo motivo, come racconto in la guideline 5.6 e il paywall.
• Ogni lingua ha il suo testo, con il vocabolario dell'app tradotta, e contato carattere per carattere.

Per TradaZen prevedo anche un messaggio in tempo reale per chi è in prova sull'abbonamento annuale. Proporrà un piano annuale più economico dello stesso gruppo, perché i miei numeri mostrano che queste persone usano l'app quanto chi paga: è il prezzo che rifiutano. Questa impostazione aspetta l'approvazione di Apple.

Cosa aspettarsi

Non contare su un miracolo. Apple chiama tasso di salvataggio la quota di abbonati che tengono l'abbonamento una volta arrivati alla pagina di conferma. Nella sessione WWDC26, Apple annuncia che gli abbonamenti che hanno adottato la Retention Messaging guadagnano in media 1,4 punti di questo tasso. I messaggi con un'offerta promozionale ottengono il miglior guadagno osservato, 5,5 punti, e i risultati variano da uno sviluppatore all'altro. Dal canto suo, lo studio di RevenueCat rileva che gli abbonati accettano solo circa l'1,1% delle offerte promozionali e lo 0,6% dei cambi di piano.

Il messaggio quindi non sostituisce il lavoro a monte. Una prova gratuita annullata nel giro di un minuto si gioca sul paywall e sulle prime sessioni: cause e leve sono nella mia guida sulla prova gratuita annullata, e la creazione della prova nell'offerta introduttiva.

Preparare l'abbonamento prima del messaggio

L'iOS & Android Kit parte dal codice di base delle mie app: onboarding, paywall e abbonamenti sono già pronti, e il percorso in quattro tappe ti porta fino all'App Store, al tuo ritmo. Tutta la catena, dai prodotti in App Store Connect al paywall, è descritta nella pagina abbonamento in-app iOS.

Se stai preparando la tua prima pubblicazione, fai la tua diagnosi gratuita: ti dice cosa blocca davvero il tuo progetto e ti manda la mia checklist anti-rifiuto di Apple.

Domande frequenti

Cos'è la Retention Messaging API di Apple?

È un servizio da server a server che sceglie il messaggio mostrato a un abbonato quando tocca Cancel Subscription. Il messaggio compare in una pagina di conferma, prima della disdetta. Può ricordare il valore dell'abbonamento, proporre un altro piano o un'offerta promozionale.

La Retention Messaging è disponibile per tutti gli sviluppatori?

L'API è un'anteprima, su richiesta di accesso ad Apple. Alla WWDC26 Apple ha annunciato un modulo in App Store Connect, aperto a tutti, previsto per l'autunno 2026. Al 3 novembre 2026, la guida di App Store Connect non lo descrive ancora.

Su quali versioni di iOS viene mostrato il messaggio?

Su iOS 15.1 e iPadOS 15.1 o successivi, su visionOS 1 e su macOS 14 o successivi. Su un dispositivo più vecchio, la disdetta avviene senza messaggio.

Il messaggio impedisce all'abbonato di disdire?

No. La pagina di conferma mantiene un pulsante per disdire. L'abbonato può anche tenere l'abbonamento, oppure accettare l'offerta o il piano proposto.

Si può proporre uno sconto al momento della disdetta?

Sì. Con l'API è un messaggio di offerta promozionale, solo in tempo reale: l'offerta viene creata in App Store Connect e firmata dal tuo server. Anche il modulo annunciato in App Store Connect permette un messaggio con un'offerta. Il cambio di piano, invece, propone un altro abbonamento dello stesso gruppo.

Quanti caratteri per un messaggio di retention?

Il titolo ha al massimo 66 caratteri, il testo 144. Puoi aggiungere fino a cinque punti elenco e un'immagine PNG senza trasparenza. Ogni lingua ha bisogno del proprio messaggio predefinito.

Serve un server per usare la Retention Messaging?

Per i messaggi predefiniti non devi ospitare nessun indirizzo: basta chiamare l'API per inviarli e registrarli. Con RevenueCat, è lui a fare da server. Il tempo reale richiede un indirizzo HTTPS che risponda in meno di 700 ms. Il modulo annunciato in App Store Connect si configura senza codice.