Misurare il churn con le notifiche in tempo reale per sviluppatori di Google Play

Google Play informa il tuo backend delle modifiche agli abbonamenti tramite le real-time developer notifications (RTDN), notifiche in tempo reale pubblicate su un topic Google Cloud Pub/Sub. Sono la base di qualsiasi monitoraggio serio del churn per un’app Android: chi ha disdetto, chi ha un problema di fatturazione, chi ha messo in pausa, chi se n’è davvero andato.

C’è un dettaglio che condiziona tutto il resto: una notifica dice solo che qualcosa è cambiato. Questa guida tratta la configurazione, come elaborare ogni messaggio, come i tipi di notifica si traducono in metriche di churn e gli errori che falsano i numeri. Si basa sulla documentazione di Google: configurare le RTDN, il riferimento RTDN, il ciclo di vita degli abbonamenti e il riferimento dell’API per purchases.subscriptionsv2 (tutti consultati a novembre 2026).

Configurare le notifiche

La guida alla configurazione di Google spiega i passaggi:

1. Crea un topic Pub/Sub in un progetto Google Cloud.
2. Assegna al service account google-play-developer-notifications@system.gserviceaccount.com il ruolo Pub/Sub Publisher sul topic.
3. Crea una sottoscrizione sul topic: push verso un endpoint HTTPS del tuo backend, o pull da un worker.
4. Nella Play Console, inserisci il nome del topic per la tua app e clicca su Send Test Message.
5. Scegli i tipi di notifica: solo abbonamenti e acquisti annullati, oppure tutto, compresi i prodotti una tantum.

Conferma (acknowledge) ogni messaggio. Per le sottoscrizioni pull, Google dice di confermare i messaggi ricevuti “per evitare consegne ripetute da parte di Cloud Pub/Sub”; per il push, un codice di risposta di successo vale come conferma.

Elaborare un messaggio

Ogni messaggio Pub/Sub ha un campo data in base64. Una volta decodificato, contiene version, packageName, eventTimeMillis ed esattamente uno tra subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, pendingRefundReviewNotification o testNotification.

Una notifica di abbonamento contiene solo un notificationType e un purchaseToken. Il riferimento di Google è esplicito: “devi chiamare la Google Play Developer API dopo aver ricevuto le notifiche in tempo reale per sviluppatori per ottenere lo stato completo”, perché le notifiche “non ti danno informazioni complete sull’acquisto”. La guida al ciclo di vita definisce purchases.subscriptionsv2.get “la fonte di verità per la gestione degli abbonamenti”.

Quindi la pipeline è:

1. Ricevi, controlla messageId per i duplicati (Google lo raccomanda), salva il messaggio grezzo, conferma.
2. Chiama purchases.subscriptionsv2.get con il purchase token.
3. Salva lo stato risultante come istantanea con il tipo di notifica e eventTimeMillis.
4. Aggiorna il diritto di accesso e le tue metriche dall’istantanea, non dalla sola notifica.

Ricorda che il purchase token funziona solo fino a 60 giorni dopo la scadenza. Recupera lo stato quando arriva la notifica, non settimane dopo.

I tipi di notifica degli abbonamenti

Dal riferimento RTDN:

Codice	Tipo	Cosa è successo
1	SUBSCRIPTION_RECOVERED	Recuperato dall’account hold, o ripreso dalla pausa
2	SUBSCRIPTION_RENEWED	Un abbonamento attivo si è rinnovato
3	SUBSCRIPTION_CANCELED	Disdetto, volontariamente o involontariamente
4	SUBSCRIPTION_PURCHASED	Nuovo abbonamento acquistato
5	SUBSCRIPTION_ON_HOLD	Entrato in account hold
6	SUBSCRIPTION_IN_GRACE_PERIOD	Entrato nel grace period
7	SUBSCRIPTION_RESTARTED	L’utente ha ripristinato un abbonamento disdetto non ancora scaduto
9	SUBSCRIPTION_DEFERRED	Data di rinnovo posticipata
10	SUBSCRIPTION_PAUSED	La pausa è entrata in vigore
11	SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED	Pausa programmata o modificata
12	SUBSCRIPTION_REVOKED	Revocato prima della scadenza
13	SUBSCRIPTION_EXPIRED	Scaduto
18	SUBSCRIPTION_CANCELLATION_SCHEDULED	Disdetta di un piano rateale programmata per la fine dell’impegno
20	SUBSCRIPTION_PENDING_PURCHASE_CANCELED	Una transazione in sospeso è stata annullata

Ce ne sono altri (elementi modificati, aggiornamenti di prezzo, consenso a un aumento di prezzo programmato). Il codice 8 è deprecato.

Gli stati che contano per il churn

Il campo subscriptionState dell’API è più affidabile del tipo di notifica per fare i conteggi. La guida al ciclo di vita descrive cosa significa ogni stato per l’accesso:

Stato	L’utente ha accesso?	Significato per il churn
SUBSCRIPTION_STATE_ACTIVE	Sì	Abbonato
SUBSCRIPTION_STATE_IN_GRACE_PERIOD	Sì	A rischio: pagamento fallito
SUBSCRIPTION_STATE_ON_HOLD	No	A rischio: pagamento fallito, accesso bloccato
SUBSCRIPTION_STATE_PAUSED	No	In pausa, non perso
SUBSCRIPTION_STATE_CANCELED	Fino a expiryTime	A rischio: rinnovo fermato
SUBSCRIPTION_STATE_EXPIRED	No	Perso

Grace period e account hold hanno valori predefiniti da conoscere. Il grace period è attivo di default su tutti i piani base a rinnovo automatico. Anche l’account hold è attivo di default, con una durata che Google calcola come 60 giorni meno il grace period. Entrambi si possono modificare nella Play Console. Prima che inizi l’account hold, Google fa altri tentativi di addebito per un massimo di 48 ore.

Dagli eventi alle metriche di churn

Conta il churn alla scadenza

SUBSCRIPTION_CANCELED significa che il rinnovo si è fermato, non che l’utente se n’è andato. Mantiene l’accesso fino a expiryTime e può ripristinarlo (SUBSCRIPTION_RESTARTED). Conta il churn su SUBSCRIPTION_EXPIRED e usa le disdette come indicatore anticipatore.

Separa churn volontario e involontario

Il canceledStateContext della risorsa abbonamento dice chi ha disdetto:

• userInitiatedCancellation: volontario. Può contenere anche la risposta al sondaggio di disdetta dell’utente.
• systemInitiatedCancellation: disdetto dal sistema, “per esempio a causa di un problema di fatturazione”. È il tuo churn involontario.
• developerInitiatedCancellation: hai disdetto tu.
• replacementCancellation: sostituito da un nuovo abbonamento, per esempio dopo un cambio di piano. Non è churn.

Il percorso della fatturazione ha una sequenza riconoscibile: SUBSCRIPTION_IN_GRACE_PERIOD, poi SUBSCRIPTION_ON_HOLD, poi SUBSCRIPTION_RECOVERED oppure, alla fine dell’account hold, SUBSCRIPTION_CANCELED seguito subito da SUBSCRIPTION_EXPIRED.

Non contare le pause come churn

SUBSCRIPTION_RECOVERED scatta sia quando un abbonamento esce dall’account hold sia quando riprende da una pausa. Controlla lo stato precedente prima di contarlo come recupero di fatturazione.

Gestisci cambi di piano e nuove iscrizioni

Upgrade, downgrade e nuove iscrizioni in-app prima della scadenza creano un nuovo acquisto con un nuovo token. Il nuovo abbonamento ha un linkedPurchaseToken che punta a quello vecchio. Se non segui questi collegamenti, ogni cambio di piano sembra un abbonato perso e uno nuovo.

Le nuove sottoscrizioni dal Play Store dopo la scadenza sono diverse: Google dice che non riportano un linkedPurchaseToken, ma la risposta dell’API include outOfAppPurchaseContext con il token scaduto finché non confermi l’acquisto. Contale come riattivazioni.

Revoche

SUBSCRIPTION_REVOKED significa che l’accesso è terminato in anticipo: l’hai revocato tu, oppure l’acquisto ha subito un chargeback. Lo stato diventa scaduto. Riportalo separatamente dal churn normale, insieme agli acquisti annullati.

Un report mensile

1. Attivi all’inizio: abbonamenti negli stati attivo, grace period o disdetto ma non scaduto.
2. Churn volontario: scadenze il cui contesto è avviato dall’utente.
3. Churn involontario: scadenze il cui contesto è avviato dal sistema.
4. Tasso di recupero della fatturazione: abbonamenti entrati in grace period o account hold e recuperati, su tutti quelli entrati.
5. Ripristini: SUBSCRIPTION_RESTARTED.
6. In pausa: quanti, e quanti riprendono.
7. Riattivazioni: nuove sottoscrizioni dal Play Store e nuove iscrizioni in-app dopo la scadenza.

Le formule generali sono in come calcolare il tasso di churn.

Errori comuni

• Fidarsi solo del tipo di notifica. Recupera sempre lo stato dell’abbonamento.
• Contare le disdette come churn. Gonfia il churn e nasconde i ripristini.
• Ignorare i purchase token collegati. I cambi di piano diventano falso churn.
• Chiamare l’API troppo tardi. I token smettono di funzionare 60 giorni dopo la scadenza.
• Non confermare i messaggi Pub/Sub. Ricevi duplicati e sprechi quota dell’API.
• Nessun account ID offuscato all’acquisto. Non puoi unire i dati di Play con i tuoi dati utente.

Farlo con NoChurn

Punti le notifiche in tempo reale per sviluppatori di Play verso NoChurn e gli dai un service account con accesso alla tua Play Console. NoChurn recupera lo stato dell’abbonamento per ogni evento, segue i purchase token collegati, separa churn volontario, di fatturazione e da revoca, e tiene una cronologia per cliente, abbinata tramite l’account ID offuscato che imposti all’acquisto. Grace period, account hold e disdette alimentano il churn score da 0 a 100, e puoi aggiungere i tuoi attributi via API. Google tiene pagamenti, nuovi tentativi e il pulsante di disdetta. Vedi NoChurn + Google Play.