App Links Android non verificati: diagnosi in cinque minuti con adb
Da Android 12, un App Link che fallisce la verifica del dominio si apre nel browser invece che nella tua app — in silenzio, e non su tutti i dispositivi. Ecco la checklist adb che trova la causa in fretta, incluso il disallineamento della chiave di firma Play dietro la maggior parte di questi incidenti.
L’app è installata. Il link apre comunque Chrome.
Di solito emerge come ticket di supporto, non come errore. Qualcuno tocca un link al tuo dominio, l’app è lì sul telefono, e si apre Chrome. Da Android 12, secondo la documentazione Android, un link https apre la tua app solo se il sistema ha verificato il dominio all’installazione — e quando quella verifica fallisce, fallisce in silenzio. Nessun crash, nessun avviso, niente nei tuoi pannelli.
Due proprietà rendono il debug faticoso. La verifica è per dominio: example.com può risultare verificato mentre promo.example.com no. Ed è per dispositivo: la stessa build può passare su un Pixel e fallire su un Samsung, una combinazione segnalata più volte nei forum sviluppatori Samsung. Se sei nel mezzo di un incidente, salta direttamente alla diagnosi.
Due domini, due verdetti
Cosa succede davvero all’installazione
All’installazione o all’aggiornamento, Android legge ogni dominio dichiarato con autoVerify e scarica https://tuodominio/.well-known/assetlinks.json per ciascuno. Secondo la documentazione Android, il file deve rispondere con un 200 diretto via HTTPS e content type application/json — il verificatore non segue i redirect. Il risultato viene messo in cache per dominio; per questo un sottodominio può essere verificato e il suo gemello no.
Nel file, sha256_cert_fingerprints deve corrispondere al certificato che ha firmato l’APK sul dispositivo. Il tranello numero uno: con Play App Signing quel certificato è la chiave di firma di Google — non la tua chiave di upload. L’impronta del keystore locale verifica benissimo le build installate a mano, e fallisce su ogni installazione arrivata dal Play Store.
Un’altra proprietà da conoscere: il verdetto è in cache. Correggere il JSON sul server non cambia nulla sui telefoni già in errore finché la verifica non gira di nuovo — cosa che, per fortuna, puoi forzare.
La diagnosi in cinque minuti
Collega un qualsiasi dispositivo Android 12+ con l’app installata ed esegui questi comandi in ordine. La maggior parte degli incidenti si risolve al passo tre.
Leggi lo stato di verifica
adb shell pm get-app-links com.example.appStampa ogni dominio dichiarato con il suo stato. verified significa che l’handshake è passato; none, che il verificatore non ha mai approvato il dominio — è quello che manda gli utenti su Chrome. Su dispositivi multiutente, controlla anche la sezione per utente in fondo.
Scarica assetlinks.json come fa il verificatore
curl -sI https://example.com/.well-known/assetlinks.jsonServe un 200 diretto. Qualsiasi 301 o 302 fa fallire la verifica, perché secondo la documentazione Android il verificatore non segue i redirect. Conferma che content-type sia application/json, poi scarica il corpo e leggi package name e impronte con i tuoi occhi. Anche una protezione anti-bot davanti a /.well-known/ conta come fallimento.
Confronta l’impronta con la chiave di firma Play
Play Console → App integrity → App signing key certificateApri quella pagina della Play Console e metti lo SHA-256 accanto al tuo JSON. Devono coincidere byte per byte. Se il file porta l’impronta della chiave di upload, hai trovato il bug — aggiungi l’impronta della chiave di firma Play, e tieni entrambe se distribuisci build anche fuori dal Play Store.
Forza una nuova verifica
adb shell pm verify-app-links --re-verify com.example.appSistemato il lato server, chiedi al dispositivo di riprovare. Il verificatore è asincrono: attendi qualche secondo, ripeti il passo uno e osserva none diventare verified. Su alcuni Samsung lo stato non si muove finché non riavvii — uno schema segnalato nei forum sviluppatori Samsung.
Lancia l’intent come un tocco reale
adb shell am start -a android.intent.action.VIEW -d "https://example.com/promo"È il test end-to-end. Su un dominio verificato l’app si apre direttamente, senza selettore. Se compare il browser o un foglio di scelta, lo stato non è ancora cambiato — ricontrolla il passo uno prima di concludere che la correzione non ha funzionato.
Se preferisci non rileggere JSON a occhio durante un incidente, il nostro strumento di validazione link scarica il tuo assetlinks.json e controlla codice di stato, content type e formato delle impronte in un solo passaggio.
I soliti sospetti
Cinque cause coprono quasi tutte le segnalazioni. Causa a sinistra, rimedio a destra.
Il JSON porta l’impronta della chiave di upload, non quella di firma Play
Copia lo SHA-256 da Play Console → App integrity → App signing key certificate. Tieni entrambe le impronte se distribuisci anche build firmate con la chiave di upload.
assetlinks.json risponde con un redirect o un 404
Servi il file direttamente su /.well-known/assetlinks.json per ogni host dichiarato. Per il verificatore, www e il dominio nudo sono due domini diversi.
Content type sbagliato, come text/html o text/plain
Configura server o CDN perché inviino application/json su quel percorso. Un JSON valido con l’header sbagliato fallisce comunque.
Più flavor o package name, uno manca dal file
Il file è un array: una dichiarazione per package name, ognuna con le sue impronte. Un flavor mancante fallisce solo per quel flavor, il che in QA sembra casuale.
Un Samsung resta su none dopo la correzione del JSON
La verifica ritardata su alcuni modelli Samsung è un tema ricorrente nei loro forum sviluppatori. Forza la ri-verifica, poi riavvia il dispositivo prima di trarre altre conclusioni.
Cosa hanno cambiato Android 15 e 16
Due release recenti hanno spostato l’asticella nella stessa direzione: gli App Links https verificati sono la strada supportata, e tutto il resto si restringe.
Ha introdotto i Dynamic App Links, secondo le note di rilascio: le associazioni di dominio possono aggiornarsi senza pubblicare un nuovo APK, accorciando il ciclo tra la correzione del JSON e la sua adozione sui dispositivi.
Ha irrigidito la verifica degli schemi URI personalizzati, secondo le note di rilascio. Se parte del tuo flusso dipende ancora da schemi myapp://, trattali come legacy e sposta quegli ingressi su link https verificati.
Dove uno smart link sta onestamente
Uno smart link instrada sul server, prima che questa macchina entri in gioco: all’apertura di un link Appy, il redirect legge il dispositivo e manda visitatori Android, iOS e desktop verso destinazioni diverse. Quel routing funziona su ogni piano e non dipende dalla verifica sul dispositivo, perché avviene prima che l’OS veda il tuo dominio.
Chiarezza su cosa non fa: uno smart link non può aggirare la verifica degli App Links. Il redirect termina sul tuo dominio https, e lo stesso stato verified-o-none decide se si apre l’app o il browser. Ciò che ti dà durante l’incidente è una porta d’ingresso controllabile — punta il traffico Android alla scheda Play Store o al web mentre ripari assetlinks.json, poi riporta la destinazione com’era senza toccare nulla di stampato, perché i QR dinamici restano modificabili dopo la stampa. Le analytics mostrano quanto traffico Android è passato dal percorso rotto.
In ogni caso, sistema la verifica. Le destinazioni deeplink su Pro e il deferred deep linking su Enterprise sono utili, ma poggiano su un assetlinks.json funzionante — non lo sostituiscono.
Domande frequenti
Perché lo stesso link funziona su un dispositivo e non su un altro?
La verifica gira su ogni dispositivo all’installazione, quindi ogni telefono conserva il proprio verdetto in cache. Un problema di rete durante l’installazione, un verificatore OEM diverso — Samsung è il caso più segnalato nei suoi forum sviluppatori — o un’installazione precedente alla correzione del JSON producono stati diversi per la stessa build.
Serve pubblicare un aggiornamento dell’app?
Di solito no. Se il manifest dichiara già il dominio con autoVerify, il guasto sta nel JSON o nell’impronta, entrambi lato server. Correggi il file, forza la ri-verifica e la build installata torna ad aprire i link. Un aggiornamento serve solo se il dominio non era mai stato dichiarato.
Uno smart link aggira la verifica?
No, e diffida di chi sostiene il contrario. Il redirect sceglie la destinazione lato server, ma quando il visitatore atterra sul tuo dominio https, il sistema applica lo stesso stato di verifica di sempre. Uno smart link cambia cosa puoi fare mentre la verifica è rotta — instradare verso store o web — non il fatto che sia rotta.
Quanto ci mette la verifica a riprovare da sola?
Secondo la documentazione Android, il verificatore ritenta i domini falliti e riparte all’aggiornamento dell’app, ma i tempi non sono garantiti e cambiano per OEM. In pratica: da ore a giorni. Forzare la ri-verifica via adb, o reinstallare l’app, è più veloce che aspettare.
Continua a esplorare
Il piano gratuito di AppsFlyer si è appena ristretto: cosa è passato a pagamento e quali opzioni hai
Deferred deep linking, domini brandizzati, Smart Banner, link in blocco e API hanno lasciato il piano gratuito Zero. Cosa è cambiato, quanto costa sostituirlo e una migrazione che sta in un pomeriggio.
Inoltro dei parametri per deeplink, Universal Link, app store e web
Scopri come conservare parametri di campagna e contesto tra app, store, Universal Link e web senza sovrascrivere i valori fissi.
Deferred deep linking: come funziona e quando usarlo
Porta l’intento originale del link oltre l’installazione, così i nuovi utenti arrivano sulla schermata giusta in-app invece che su una home generica.
Cerchi altro? Sfoglia tutti gli argomenti su il blog.
Dai al traffico Android un posto dove atterrare
Crea uno smart link che rileva il dispositivo lato server e instrada i visitatori Android verso app, store o web — e cambia la destinazione in seguito senza ristampare un solo QR code.
Crea uno smart link gratis