Universal Links e App Links: i codici di errore spiegati
SWCERR00101, SWCERR00301, legacy_failure, 1026: cosa significa davvero ogni errore di Universal Links e Android App Links, dove lo trovi e cosa correggere perché l’app torni ad aprirsi. Oppure lascia che il validatore gratuito di Appy trovi il problema per te, in pochi secondi.
Prima di tutto, verifica che sia davvero rotto
Molte segnalazioni del tipo «gli Universal Links non funzionano» riguardano link che si comportano esattamente come Apple li ha progettati. La technote TN3155 di Apple elenca i casi in cui l’app deve restare chiusa: un URL digitato o incollato nella barra degli indirizzi di Safari è navigazione diretta, quindi resta al browser. Anche un link allo stesso dominio della pagina su cui ti trovi resta nel browser. E i browser di terze parti, compresi quelli integrati in altre app, decidono da soli se passare un link alla tua app.
Quindi fai un test onesto prima di toccare anche un solo file. Incolla il link in Note sull’iPhone e tienilo premuto. Se la configurazione è corretta, il menu propone di aprirlo nella tua app oltre che nel browser. Quello che l’utente sceglie lì diventa l’impostazione predefinita per quel dominio: un altro motivo silenzioso per cui un link che ieri funzionava oggi apre Safari.
Se Note non propone l’app, c’è un problema nell’associazione, e il codice di errore ti dice quale.
La scorciatoia: il validatore gratuito di Appy
Prima di aprire un terminale, incolla il tuo dominio nel validatore di Universal Links di Appy. Scarica il file apple-app-site-association dal tuo server e, separatamente, dalla CDN di Apple, così vedi subito se Apple ha lo stesso file che hai tu. Chiede anche all’API Digital Asset Links di Google cosa legge Android dal tuo assetlinks.json. Gratis, senza registrazione, con un’unica pagina di risultati da girare ai tuoi sviluppatori.
Se il problema sono i file stessi, il generatore di AASA e assetlinks.json di Appy li scrive entrambi a partire da Team ID, bundle ID e impronta SHA-256. Il resto della guida spiega ogni errore, così sai esattamente cosa correggere quando il validatore ne segnala uno.
Chiedi alla CDN di Apple cosa ha in mano
Da iOS 14 i telefoni non scaricano mai il file apple-app-site-association dal tuo server. Lo ricevono dalla CDN di Apple, che a sua volta lo scarica da te. Quindi la prima domanda non è «il mio file è giusto?», ma «cosa ha Apple?».
Cosa conserva la CDN di Apple per il tuo dominio
curl -sD - "https://app-site-association.cdn-apple.com/a/v1/links.example.com" -o /dev/nullUn dominio con errori risponde così
HTTP/1.1 404 Not Found
Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found
Cache-Control: max-age=3600,publicIl tuo server, come lo vede la CDN
curl -v -A "AASA-Bot/1.0" https://links.example.com/.well-known/apple-app-site-associationI codici SWCERR e come risolverli
Apple non pubblica un elenco di questi codici. Quelli qui sotto sono i messaggi che la CDN di Apple restituisce nell’header Apple-Failure-Reason, ognuno confermato in discussioni sugli Apple Developer Forums o nelle nostre richieste alla CDN.
SWCERR00101 · Bad HTTP Response: 404 Not Found
La CDN ha chiesto il tuo file e ha ricevuto qualcosa di diverso da un 200. Il caso più comune: il file si trova sul dominio principale mentre l’entitlement indica un sottodominio, o viceversa. Ogni host in applinks: ha bisogno del proprio file su https://that-host/.well-known/apple-app-site-association. Un 502 qui significa che il tuo server di origine era giù quando Apple l’ha interrogato.
SWCERR00201 · Insecure (non-https) redirects forbidden
L’URL del file reindirizza a un indirizzo http://. Servilo direttamente in HTTPS su ogni dominio. La documentazione di Apple dice niente redirect, punto; nei nostri test la CDN ha seguito un redirect da https a https, ma un passaggio a http fallisce sempre.
SWCERR00202 · Connections to private/reserved IP addresses are not allowed
L’hostname si risolve in un indirizzo privato o riservato, quindi Apple non si connette. Succede spesso con i domini di staging che esistono solo dentro una VPN. Per quelli usa la modalità sviluppatore (ne parliamo più sotto) e per la produzione un host pubblico.
SWCERR00301 · Timeout
Il fetcher di Apple ha aspettato e non ha ricevuto nessun header. Di solito la causa sono firewall, blocchi geografici e protezioni anti-bot che sottopongono a verifica i client sconosciuti. Apple dice che il file deve essere raggiungibile da qualsiasi IP e non pubblica i suoi intervalli di indirizzi, quindi apri quel percorso a tutti.
SWCERR00302 · Network error (temporary)
Un errore temporaneo, spesso di DNS. Se il tuo DNS è a posto, di solito sparisce al fetch successivo, che per un errore arriva entro un’ora.
SWCERR00303 · TLS error
Il certificato è scaduto, è stato emesso per un altro host, è autofirmato, oppure l’handshake è fallito. Apple vuole un certificato pubblicamente attendibile che copra esattamente quell’hostname. Un certificato per example.com non copre links.example.com, a meno che non lo indichi esplicitamente.
SWCERR00305 · Network error
La CDN si è connessa, ma il trasferimento si è interrotto: EOF, connection refused, oppure gzip: invalid header quando il server dichiara una compressione che poi non applica. Controlla le impostazioni del WAF e della compressione per quel percorso.
SWCERR00401 · Bad JSON content
La CDN ha ricevuto qualcosa che non è JSON, di solito una pagina HTML di verifica anti-bot o una pagina di login. Il dettaglio «invalid character ‘<’» lo tradisce. La soluzione suggerita da un ingegnere Apple nei forum: fare in modo che il server restituisca il file così com’è a qualsiasi user agent, compreso AASA-Bot/*.
Controlla i percorsi con swcutil
Quando Apple ha il file, la domanda successiva è se il tuo link ci corrisponde. Su un Mac, swcutil verifica una copia locale del file rispetto a un URL reale: è il controllo che gli ingegneri Apple consigliano al posto della modalità sviluppatore.
Test di download
sudo swcutil dl -d links.example.comTest di corrispondenza
sudo swcutil verify -d links.example.com -j ./apple-app-site-association -u https://links.example.com/promoCome appare una corrispondenza
{ s = applinks, a = ABCD123.com.example.app, d = links.example.com }:
Pattern "https://links.example.com/promo" matched.Cosa ne pensa il telefono
Con la modalità sviluppatore attiva, in Impostazioni › Sviluppatore › Universal Links c’è una schermata Diagnostics: inserisci un URL completo e ti dice se un’app installata lo rivendica. Per il quadro completo, fai un sysdiagnose e apri swcutil_show.txt. Cerca il tuo app ID e leggi tre righe.
Site/Fmwk Approval dovrebbe dire approved. Unspecified o denied significa che il telefono non ha mai ricevuto un file approvato per quell’app e quel dominio: controlla l’entitlement, l’accesso pubblico e il prefisso del Team ID. User Approval mostra se la persona ha scelto il browser per questo dominio. Last Checked e Next Check indicano quando Apple ha scaricato il tuo file l’ultima volta.
Quest’ultimo punto spiega quasi tutti i momenti «l’ho sistemato ma non è cambiato niente». Dopo l’installazione, un telefono ricontrolla il file più o meno una volta a settimana. Per provare subito una correzione, reinstalla l’app. Per lo staging, aggiungi ?mode=developer alla voce applinks: salta la CDN, ma solo per le build firmate per lo sviluppo, sui dispositivi in cui hai attivato l’opzione.
I numeri da ricordare
- per quanto la CDN di Apple ha tenuto un file valido nei nostri test
- 6 h
- per quanto ha tenuto un errore
- 1 h
- ogni quanto un iPhone ricontrolla dopo l’installazione
- ~1 settimana
- l’attesa minima su Android prima di controllare la verifica
- 20 s
per quanto la CDN di Apple ha tenuto un file valido nei nostri test
per quanto ha tenuto un errore
ogni quanto un iPhone ricontrolla dopo l’installazione
l’attesa minima su Android prima di controllare la verifica
Android App Links: gli stati riportati da pm get-app-links
Su Android non c’è una CDN in mezzo. Il verificatore del dispositivo scarica da solo https://your-host/.well-known/assetlinks.json e, da Android 12, un link non verificato non mostra più la finestra di scelta: si apre e basta nel browser. Ecco perché un’impronta mancante sembra proprio «il link funziona, solo non nella mia app».
Android 12 ha cambiato anche il modo in cui vengono valutati più host. Ora ogni host viene verificato per conto suo; su Android 11 e versioni precedenti, se un host non supera la verifica falliscono tutti. E su Android 15 una modifica ad assetlinks.json può impiegare fino a sette giorni per arrivare a tutti i dispositivi.
Rilancia la verifica dal tuo portatile
Reimposta, verifica, leggi
adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app
adb shell pm get-app-links com.example.appOutput tipico
example.com: verified
sub.example.com: legacy_failure
example.org: 1026Cosa significa ogni stato
verified
Il dominio ha superato la verifica. Se i link aprono ancora il browser, guarda l’intent filter: android:autoVerify="true", la categoria BROWSABLE ed entrambi gli schemi, http e https.
none
Non è ancora registrato niente. Aspetta qualche minuto e lancia di nuovo verify-app-links.
legacy_failure
Il verificatore legacy ha rifiutato il dominio senza dire perché. Parti dal file stesso: HTTP 200, application/json, HTTPS, nessun redirect.
1024 e oltre (per esempio 1026)
Un errore specifico del verificatore. La documentazione di Android rimanda alla rete e all’hosting: le stesse regole su 200, JSON, HTTPS e niente redirect.
approved / denied
Imposto da un comando shell, non dalla verifica. Reimposta con set-app-links prima di fidarti di qualsiasi risultato.
migrated / restored / system_configured
Ereditato dalla verifica legacy, ripristinato con i dati utente o impostato dalla configurazione del dispositivo. Non sono errori, ma nemmeno la prova che oggi il tuo file funzioni.
L’impronta giusta sul tuo portatile e sbagliata sul Play Store
Il guasto più comune su Android non ha niente a che fare con l’hosting. Con Play App Signing, Google firma di nuovo la tua app con la propria chiave di firma. Lo SHA-256 che ottieni con keytool dalla tua chiave di caricamento non è quello che finisce sui telefoni degli utenti, quindi la build di release fallisce mentre quella locale passa.
Copia invece l’impronta da Play Console › Release › Setup › App signing. L’array sha256_cert_fingerprints accetta più valori, quindi lascia lì anche la tua chiave di debug, in maiuscolo. E ricorda che un redirect da example.com a www.example.com, o da http a https, significa che Android non verifica nessuno dei tuoi link.
Guarda cosa legge Google dal tuo file
API Digital Asset Links
curl "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls"Le campagne restano attive mentre sistemi
Dei file di associazione rotti non dovrebbero costarti installazioni. Un link Appy manda ogni telefono allo store giusto su tutti i piani, Huawei AppGallery compreso, e con Pro prova prima la tua app, così chi ce l’ha già ci finisce dentro. Niente file AASA, niente SDK, nessun rilascio dell’app. Quando gli Universal Links tornano a funzionare, tieni lo stesso link Appy: codici stampati e post non cambiano.
appy.to/yourapp
funziona mentre fai debug
- iPhoneLa tua app con Pro, o l’App Store
- AndroidLa tua app con Pro, o Google Play
- HuaweiAppGallery
- ComputerIl tuo sito web
Leggi anche
- Validatore di Universal LinksControlla in un colpo solo il tuo AASA sul tuo server e sulla CDN di Apple, più assetlinks.json.
- Generatore di AASA e assetlinks.jsonScrive entrambi i file a partire da Team ID, bundle ID e SHA-256.
- Gli Universal Links aprono Safari invece dell’appLe cause legate al comportamento, dalla regola dello stesso dominio alla scelta dell’utente.
- Verifica degli Android App Links non riuscitaUn’analisi più approfondita del lato Android.
Domande sui codici di errore
Dove vedo i codici SWCERR?
Nell’header Apple-Failure-Reason quando richiedi https://app-site-association.cdn-apple.com/a/v1/your-domain, nell’output di swcutil dl su un Mac e nel log di swcd su un dispositivo.
Come faccio a far prendere ad Apple il file AASA corretto?
Non puoi svuotare la CDN di Apple. La CDN riscarica il file quando la cache scade, e nei nostri test per gli errori succedeva dopo un’ora. Poi reinstalla l’app sul telefono di test, così scarica la nuova copia invece di aspettare il controllo settimanale.
Il file apple-app-site-association ha un limite di dimensione?
Nel 2016 Apple ha documentato un limite di 128 KB. La documentazione attuale non lo ripete, ma tenere il file piccolo toglie ogni dubbio.
Perché il link apre il browser quando lo digito in Safari?
È previsto. Gli URL digitati e i link all’interno dello stesso dominio restano nel browser per scelta di progetto. Fai il test da Note o da Messaggi.
Cosa significa legacy_failure su Android?
Il verificatore legacy ha rifiutato il dominio e Android non dice perché. Controlla che assetlinks.json risponda 200 come application/json in HTTPS senza redirect e che contenga l’impronta di Play App Signing.
Posso evitare tutto questo?
In parte. Con il piano Pro un link Appy prova prima lo URL scheme della tua app e, se non va, passa allo store giusto, quindi funziona senza file AASA sul tuo dominio. Per i veri Universal Links serve comunque la configurazione descritta sopra.
Esiste uno strumento che controlla tutto questo in un colpo solo?
Sì. Il validatore di Universal Links di Appy è gratuito e non richiede registrazione. Controlla il tuo file AASA sul tuo server e sulla CDN di Apple, e il tuo assetlinks.json tramite l’API Digital Asset Links di Google, poi ti dice cosa correggere.
Continua a esplorare
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. La checklist adb che trova la causa in fretta.
Universal Links aprono Safari? Correggi AASA, App Links, redirect e header
Workflow pratico per risolvere universal links e app links che aprono il browser invece dell’app.
Come i browser in-app gestiscono i deep link: Instagram, TikTok, Facebook, Gmail, Telegram e altri
Il tuo link apre l’app da Safari ma non dentro Instagram. Cosa fanno i browser in-app di Instagram, TikTok, Facebook, Gmail, Telegram e altri, le regole di iOS e Android e come prevedere un fallback.
Cerchi altro? Sfoglia tutti gli argomenti su il blog.
Basta clic persi per colpa di link rotti
Trova il file rotto con il validatore gratuito e, nel frattempo, tieni in piedi ogni campagna con un link Appy: lo store giusto su tutti i piani, la tua app con Pro.