Flussi pronti, zero push recapitate: il Missing Push Token che blocca il 100% delle notifiche Klaviyo

Settore: app di loyalty con gamification — iOS e Android, consumer
Problema: SDK Klaviyo integrato, flussi push configurati, zero notifiche consegnate — tutti “Missing Push Token”
Causa: push token agganciato al profilo anonimo, non al profilo identificato con email
Fix: correzione del momento di identificazione utente nell’SDK
Complessità aggiuntiva: deep link per navigazione in-app + iOS Universal Links e Android App Links per le email

---

“Il flusso è online, tutti gli errori dicono Missing Push Token. Nemmeno una push recapitata.”

Tre settimane di lavoro: mappatura degli eventi su Miro, allineamento con il team di sviluppo, configurazione dei flussi in Klaviyo, test interni. Poi il primo flow live — un semplice post-signup — e zero consegne. Non il 50%, non il 20%. Zero.

L’SDK era installato. I token venivano generati. Klaviyo li riceveva. Ma quando i flussi cercavano di inviare, non trovavano nulla sui profili degli utenti reali.

Questo è il bug più silenzioso dell’integrazione Klaviyo mobile: si manifesta solo quando si tenta il primo invio reale, e quando appare è già tardi — gli utenti si sono già registrati, i token già emessi, tutto apparentemente corretto.

---

Il contesto: app con Firebase già attiva, Klaviyo in parallelo

Il brand gestisce un’app consumer iOS e Android con un sistema di loyalty gamificato: scan di scontrini, accumulo punti, premi, giochi interni. Firebase era già installato e funzionante per analytics e remote config. Il progetto era aggiungere Klaviyo SDK in parallelo — non in sostituzione di Firebase, ma come layer separato per email marketing e push notification.

Il piano concordato:

1. Mappatura completa degli eventi necessari su Miro (eventi custom: scan scontrino, riscatto premio, completamento gioco, ecc.)
2. Allineamento con il team di sviluppo esterno (l’agenzia che gestisce l’app)
3. Implementazione SDK su iOS e Android
4. Fase di verifica interna da parte nostra
5. Go-live: push notification e segmentazione email attive in Klaviyo

Timeline stimata: tre settimane. Priorità dichiarata: le push notification, più urgenti delle email per il business del brand.

Tutto in ordine. Fino al primo test live.

---

Il problema: zero push consegnate, tutti “Missing Push Token”

Il primo flusso attivato era intenzionalmente semplice: un post-signup con una singola notifica push di benvenuto. Nessuna logica complessa, nessun targeting avanzato. Puro test di funzionamento.

Risultato: ogni singolo messaggio in errore con lo stesso messaggio — “Missing Push Token”. Nemmeno una push consegnata.

Le cause possibili identificate nell’immediato:

Causa	Probabilità	Come verificarla
App disinstallata	Bassa (utenti attivi)	Controllare retention recente
Notifiche non autorizzate	Parziale	Testare con account interni
SDK non installato/aggiornato correttamente	Alta	Controllare versione SDK e chiamate
Utente non identificato → token su profilo sbagliato	Alta	Ispezionare profili in Klaviyo

La strategia di debug: usare account interni con notifiche attive e app aperta di recente per testare. Se anche quelli tornano “Missing Push Token”, il problema è nell’integrazione — non nel comportamento degli utenti.

---

La causa: identificazione troppo tardiva (o assente)

Klaviyo gestisce i profili in modo stateful. Quando l’SDK si inizializza su un dispositivo, crea immediatamente un profilo — anonimo, identificato dal solo device ID. Quando l’OS concede il push token (dopo che l’utente accetta le notifiche), l’SDK registra quel token sul profilo attivo in quel momento.

Se l’utente non è ancora stato identificato con la propria email — attraverso la chiamata identify dell’SDK — il push token viene registrato sul profilo anonimo, non su quello con email.

Quando in seguito l’utente si registra o fa login e viene identificato (identify(email: "...")), Klaviyo crea o aggiorna il profilo identificato. Ma il push token rimane sul vecchio profilo anonimo. I due profili coesistono, con il token nel posto sbagliato.

I flussi Klaviyo inviano ai profili con email. Cercano il token su quel profilo. Non lo trovano. “Missing Push Token”.

Capsule citabile: Il “Missing Push Token” in Klaviyo mobile non segnala che il token non esiste — segnala che il token esiste su un profilo diverso da quello a cui il flusso sta cercando di inviare. È il risultato di un’identificazione tardiva nell’SDK: il token viene registrato sul profilo anonimo del dispositivo prima che l’utente venga identificato con la propria email. Il fix è strutturale — l’SDK deve chiamare identify prima (o contestualmente) alla richiesta del permesso push, non dopo il signup o il login.

---

Il fix: identificazione sincronizzata con il token

La correzione richiede un intervento nell’app, non in Klaviyo. L’agenzia di sviluppo ha sistemato il punto di chiamata di identify nell’SDK.

Il pattern corretto per iOS (KlaviyoSwift) e Android (klaviyo-android-sdk):

Sequenza corretta:

1. Utente apre l’app per la prima volta
2. Se l’utente è già loggato (sessione persistente) → identify con email prima di richiedere il permesso push
3. Richiesta permesso notifiche → token generato → SDK lo registra sul profilo già identificato
4. A ogni apertura successiva → setProfile aggiorna il token se cambiato

Edge case critico — primo signup: Se l’utente non ha ancora un account, il token viene emesso prima che esista un’email. In questo caso l’SDK deve essere configurato per ri-propagare il token immediatamente dopo il completamento del signup, chiamando di nuovo il metodo di registrazione del token sul profilo ora identificato.

// iOS — KlaviyoSwift
// Dopo login/signup, chiama sempre:
KlaviyoSDK().set(profileAttribute: .email, value: "user@example.com")
// L'SDK re-associa il token al profilo identificato automaticamente

// Android — klaviyo-android-sdk
// Dopo login/signup:
Klaviyo.setEmail("user@example.com")
// Il token esistente viene propagato al profilo aggiornato

---

La complessità in più: deep link da notifiche push

Una volta risolto il token, il passaggio successivo era rendere le push utili. Una notifica che porta alla home app è meno efficace di una che porta direttamente alla schermata rilevante. Per questo erano necessari i deep link.

Le schermate da mappare:

Schermata	Deep link target	Note
Premi	urkah://premi	Lista premi disponibili
Giochi	urkah://giochi	Accesso area gamificata
Upload scontrino	urkah://scan	Flusso scan/upload per punti
Saldo punti	urkah://punti	Wallet punti utente
Home	—	Nessun deep link necessario, tap standard

I deep link custom URL scheme (urkah://) funzionano per le push notification native. Ma per le email era necessario qualcosa di diverso.

---

Universal Links per le email: iOS e Android

Nelle email, un link del tipo urkah://premi non funziona: i client email non aprono URL scheme custom per ragioni di sicurezza. La soluzione è iOS Universal Links (HTTPS) e Android App Links.

Con Universal Links / App Links, lo stesso URL HTTPS (https://urkah.it/premi) si comporta diversamente in base al contesto:

• App installata e utente loggato → apre direttamente la schermata Premi nell’app
• App non installata → apre https://urkah.it/premi nel browser

Per abilitarli, l’agenzia di sviluppo deve:

1. iOS: hostare apple-app-site-association in https://urkah.it/.well-known/apple-app-site-association con il mapping percorso → bundle ID
2. Android: hostare assetlinks.json in https://urkah.it/.well-known/assetlinks.json con il mapping dominio → app fingerprint
3. Klaviyo: abilitare click tracking dedicato — Klaviyo gestisce i propri redirect tramite sottodominio personalizzato (click.urkah.com), che deve a sua volta supportare il passthrough verso gli Universal Link

Capsule citabile: Nelle campagne email Klaviyo, gli URL scheme custom (tipo app://schermata) non funzionano nei client email per ragioni di sicurezza. La soluzione è iOS Universal Links e Android App Links: URL HTTPS normali che il sistema operativo intercetta e indirizza all’app (se installata) oppure al browser (se non installata). Richiedono un file well-known hostato sul dominio dell’app, più la configurazione del click tracking dedicato in Klaviyo su sottodominio personalizzato.

---

Email infrastruttura: DMARC, SPF, DKIM

Prima che qualsiasi email potesse partire da Klaviyo (flussi o campagne), era necessario verificare il dominio mittente. Il brand inviava da info@urkah.com, dominio gestito su AWS Route 53.

I record necessari:

• SPF: autorizzare i server Klaviyo come sender legittimi per il dominio
• DKIM: firma crittografica di Klaviyo aggiunta ai record DNS
• DMARC: policy già configurata su AWS — nessun intervento necessario

I record SPF e DKIM erano stati aggiunti, ma la verifica in Klaviyo ci ha richiesto qualche ora perché la propagazione DNS su Route 53 richiedeva un po’ di tempo. Nel frattempo: tutti i flussi email bloccati. Nessun invio possibile finché il dominio non risultava verificato.

Ordine di operazioni che evita questi blocchi:

1. Aggiungere i record DKIM Klaviyo in DNS prima di configurare qualsiasi flusso
2. Attendere propagazione (fino a 48h, tipicamente molto meno)
3. Verificare domain status in Klaviyo prima di attivare flussi
4. Solo dopo: iniziare a costruire flussi

Se si attivano i flussi prima che il dominio sia verificato, Klaviyo blocca tutti gli invii silenziosamente — nessuna email parte, ma non appare un errore chiaro nel flow builder.

---

Migrazione da Mailchimp: le template si recuperano, ma a mano

Il brand aveva template email in Mailchimp che voleva recuperare per Klaviyo. La cattiva notizia: Mailchimp non ha un export massivo delle immagini.

Il processo manuale necessario:

1. Aprire la campagna Mailchimp
2. Selezionare ogni immagine → copiare l’URL dell’immagine
3. Aprire l’URL nel browser → salvare il file

Un’immagine alla volta. Per campagne con molte creative, questo diventa un lavoro significativo che richiede una figura dedicata — non ha senso che lo faccia chi si occupa della configurazione dei flussi.

La strategia scelta: non fare l’export massiccio, ma identificare le campagne più simili a quelle da rilanciare e recuperare solo le immagini strettamente necessarie. Le altre vengono ricreate da zero in Klaviyo al momento del bisogno.

---

Checklist: cosa verificare prima del go-live Klaviyo mobile

Basata sui blocchi incontrati in questo progetto:

Prima di configurare i flussi:

• Dominio mittente verificato in Klaviyo (SPF + DKIM nei DNS)
• DMARC presente nel DNS del dominio
• SDK installato in versione corrente su iOS e Android
• identify chiamato prima o contestualmente alla richiesta permesso push
• Test con account interni: inviare una push manuale e verificare consegna

Prima del go-live email:

• Propagazione DNS completata (verificare con tool MX Toolbox o simili)
• Dominio marcato come “verified” in Klaviyo settings
• Almeno un flusso test inviato a indirizzo interno e ricevuto

Deep link e Universal Links:

• URL scheme custom configurati nell’app per push notification
• apple-app-site-association pubblicato e accessibile
• assetlinks.json pubblicato e accessibile
• Sottodominio click tracking Klaviyo configurato e testato
• Test clic da client email reale (Gmail, Apple Mail, Outlook) su dispositivo con app installata

---

Cosa è cambiato dopo il fix

• Push notification operative — flussi post-signup e re-engagement attivi
• Deep link configurati per le 4 schermate chiave (premi, giochi, scan, saldo punti)
• Dominio verificato — email da flussi e campagne in uscita
• Universal Links in lavorazione per click email → apertura diretta in-app
• Segmentazione per comportamento in-app abilitata in Klaviyo

Il blocco totale di 100% “Missing Push Token” era risolvibile in poche ore una volta identificata la causa. Ma identificare la causa ha richiesto di separare quattro possibili spiegazioni — e di testare sistematicamente.

---

Domande frequenti

Come faccio a sapere se i miei push token sono sul profilo sbagliato?

In Klaviyo, vai in Audience → Profiles e cerca un profilo con email di un utente che ha l’app installata. Nella scheda Push Tokens verifica se ci sono token associati. Se il profilo con email non ha token, ma aprendo il profilo anonimo dello stesso dispositivo (identificabile da device_id nei log dell’SDK) il token è presente, hai il problema di identificazione tardiva.

Il problema si verifica solo per i nuovi utenti?

Principalmente sì. Gli utenti che si sono registrati prima dell’implementazione dell’SDK non hanno mai avuto identify chiamato durante la sessione in cui il token è stato emesso. Per questi utenti, il fix si applica al prossimo accesso: se l’SDK chiama identify correttamente all’apertura dell’app e l’utente è già loggato, il token viene re-propagato al profilo corretto.

Klaviyo e Firebase Push possono coesistere sulla stessa app?

Sì. Entrambi gli SDK possono ricevere il push token dell’OS. Bisogna però gestire manualmente il routing delle notifiche: le push inviate da Firebase vengono gestite da Firebase, quelle da Klaviyo da Klaviyo. Se non viene gestita la distinzione, entrambi gli SDK potrebbero intercettare notifiche non loro e comportarsi in modo imprevedibile. Le documentazioni di entrambi gli SDK descrivono come configurare il passthrough corretto.

Gli Universal Links per email richiedono che il file well-known sia accessibile senza redirect?

Sì. Sia apple-app-site-association (iOS) che assetlinks.json (Android) devono essere accessibili via HTTPS senza redirect, con Content-Type: application/json. Se il file è presente ma il server risponde con un redirect 301 prima di servire il file, il sistema operativo non lo legge e i link non si aprono in-app.