assetlinks.json SHA-256 dopo Play App Signing: elimina la barra del browser nella TWA

Questa guida tratta una sola riparazione: l’associazione tra il tuo sito e la build distribuita da Google Play. Non tratta la creazione della TWA né la revisione dell’app da parte di Play, che hanno guide dedicate linkate più sotto. Ogni pagina Google citata qui è stata verificata il 16 ottobre 2026 e le fonti sono elencate alla fine.

Perché la barra del browser compare solo sull’installazione da Play

Chrome verifica una TWA confrontando il certificato che ha firmato l’app installata con le impronte pubblicate dal tuo sito. Quando questo controllo non riesce, la guida rapida alle TWA di Chrome spiega che il browser ripiega mostrando il tuo sito come Custom Tab. Quel ripiego è la barra degli indirizzi che vedi.

Con Play App Signing di solito ci sono due certificati. Firmi il bundle che carichi con la tua chiave di caricamento, e Google firma gli APK che distribuisce con la chiave di firma dell’app. La pagina di Chrome Android concepts for web developers spiega che l’impronta della chiave di firma dell’app è quella che corrisponde alla tua app quando viene scaricata dal Play Store. Un file che elenca solo il tuo certificato locale quindi funziona sulla tua scrivania e fallisce su ogni telefono che ha installato da Play.

Le due chiavi non sono sempre diverse. La documentazione Android sulla firma delle app descrive configurazioni in cui la stessa chiave fa sia da chiave di firma dell’app sia da chiave di caricamento. Quindi la soluzione è confrontare i certificati reali, non dare per scontato quale hai.

Trova lo SHA-256 della firma dell’app in Play Console

La documentazione di Google al momento indica due etichette per lo stesso punto. Entrambe partono da Protected with Play nel menu a sinistra della tua app.

Le guide più vecchie, comprese alcune pagine Google, indicano ancora Release > Setup > App signing oppure Setup > App integrity. Se trovi solo queste etichette, stai cercando la stessa pagina con un nome precedente.

Leggi l’impronta di una chiave che possiedi tu

Per la tua chiave di caricamento o una chiave di debug, keytool di Java stampa lo stesso formato. Sostituisci il file keystore e l’alias con i tuoi, poi copia la riga etichettata SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Se gestisci molte app, anche la Google Play Developer API può restituire l’hash del certificato degli APK generati da Play (il campo certificateSha256Hash dell’elenco degli APK generati). Per una singola correzione è più semplice copiarlo da Play Console.

Scrivi e servi un assetlinks.json corretto

Il file è un array JSON di dichiarazioni. Per una TWA la relazione è delegate_permission/common.handle_all_urls e il target è la tua app Android: il namespace android_app, il tuo ID applicazione esatto e un array di impronte SHA-256. Un file minimo è così:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Sostituisci com.example.twa con il tuo ID applicazione e ogni segnaposto con uno SHA-256 completo separato da due punti. Elimina la seconda voce se ti serve solo che vengano verificate le installazioni da Play. Solo JSON rigoroso: niente commenti, niente virgole finali, niente valori SHA-1.

Come Google richiede che il file venga servito

• Posizione esatta. https://your-domain/.well-known/assetlinks.json, con il punto in .well-known. example.com e www.example.com sono origini diverse; pubblica il file su ognuna di quelle che la tua app apre. Una copia in una sottodirectory come /app/.well-known/ non conta.
• Un HTTP 200 diretto. La documentazione di Digital Asset Links di Google dice: “Qualsiasi risposta del server diversa da HTTP 200 viene trattata come un errore e produce un elenco di dichiarazioni vuoto.”
• Nessun reindirizzamento. Le risposte 301 e 302 non vengono seguite. Questo include un passaggio da http a https e da dominio senza www a www.
• HTTPS con una catena di certificati valida e l’header Content-Type: application/json. Una pagina di login o una pagina di errore HTML che risponde con 200 non è un file valido.

Controlla la risposta live da qualsiasi terminale. La prima riga di stato deve essere 200 e il content type deve essere JSON, senza alcun 3xx prima:

curl -sI https://example.com/.well-known/assetlinks.json

Più di un’impronta, più di un’app

La guida Android sull’associazione con il sito web dice dell’array di impronte: “Questo campo supporta più impronte, che possono essere usate per supportare versioni diverse della tua app, come le build di debug e di produzione.” Aggiungi un’impronta di caricamento o di debug solo per le build di cui vuoi davvero che quel sito si fidi. Una build con un ID applicazione diverso, come un pacchetto di debug separato, richiede una propria dichiarazione nell’array.

Se hai creato la TWA con Bubblewrap o PWABuilder

In un progetto Bubblewrap esistente, aggiungi l’impronta di Play e rigenera il file:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Generare il file non significa pubblicarlo: carica il nuovo assetlinks.json sul tuo sito e controllalo con curl. bubblewrap validate controlla la tua PWA rispetto a criteri di qualità; non controlla l’associazione della firma, quindi superarlo non dimostra nulla sull’impronta. Le istruzioni attuali di PWABuilder dicono lo stesso sulla firma, “Una volta caricato il file .aab, Google Play firma di nuovo la tua app”, e ti chiedono di aggiungere l’impronta di Play al file generato. Correggere un’impronta è una modifica al tuo sito, non al binario dell’app.

Verifica l’associazione, poi testa l’installazione da Play

Entrano in gioco quattro livelli: il file sul tuo sito, la Digital Asset Links API di Google, la verifica dei link di Android e il browser che avvia la tua TWA. Superare un livello non dimostra il successivo, quindi controllali in ordine e finisci sul dispositivo.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

App Links Assistant di Android Studio (Tools > App Links Assistant) controlla l’associazione degli Android App Links e il tuo manifest. È utile per questi aspetti, ma non ti dice se la tua TWA si apre a schermo intero; lo dice solo il test sul dispositivo.

Avanzato: lo stato di verifica di Android

Su Android 12 e versioni successive, la guida alla verifica di Android documenta questi comandi per gli App Links. Sostituisci il pacchetto, esegui i primi due, attendi qualche minuto, poi leggi lo stato:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified descrive la verifica del dominio di Android, non se la tua TWA si apre senza l’interfaccia del browser. I codici da 1024 in su sono errori specifici del verificatore, non una diagnosi di uno SHA-256 errato. Per la TWA in sé, usa il log di Chrome qui sopra.

L’impronta coincide ma la barra resta

Una barra visibile non dimostra che lo SHA-256 sia sbagliato. Quando il controllo qui sopra restituisce linked: true e la barra c’è ancora, esamina queste cause.

Quanto tempo prima che un file corretto abbia effetto

Google non pubblica un tempo di attesa unico per le TWA, perché entrano in gioco diverse cache e ognuna ha le sue regole:

• Il tuo server o la CDN potrebbe servire ancora il vecchio file. Svuota la cache e conferma la risposta live con curl.
• La Digital Asset Links API indica per quanto tempo ogni risposta resta valida nel campo maxAge.
• Gli Android App Links hanno tempi propri. La guida alla verifica di Android dice che su Android 15 e versioni successive le modifiche possono richiedere fino a sette giorni per raggiungere tutti i dispositivi, e che su Android 14 e versioni precedenti il file viene in genere letto quando l’app viene installata o aggiornata.
• Il browser potrebbe conservare un proprio stato. Uno sviluppatore ha segnalato di aver risolto cancellando i dati di Chrome.

Quindi svuota la cache, conferma il file live e reinstalla da Google Play. Su un dispositivo di test, una nuova installazione o la cancellazione dei dati del browser può escludere uno stato in cache; è un passaggio diagnostico, non qualcosa da chiedere a ogni utente. Non fare piani basati su un numero fisso di ore.

Rifiuto, revisione e test chiuso

Un assetlinks.json mancante o errato non è documentato come causa di rifiuto di per sé. Ciò che la documentazione descrive è il ripiego su una Custom Tab con l’interfaccia del browser. La revisione è una questione separata: le norme sulla funzionalità di Google Play dicono “Non consentiamo app che si arrestano in modo anomalo, si chiudono forzatamente, si bloccano o funzionano in modo anomalo in altri modi”, e questo vale qualunque sia lo stato della tua associazione. Un’impronta corretta elimina la barra; non risolve la revisione. Se hai ricevuto un rifiuto, parti dalle norme indicate nell’email.

Alcuni articoli più vecchi dicono che Chrome fa arrestare una TWA che non supera i controlli di qualità. Chromium ha rimosso quel codice QualityEnforcer il 4 maggio 2023, quindi considera quel consiglio come storico e non come una descrizione dei browser di oggi.

Se hai ricevuto un rifiuto, parti dal motivo indicato nella notifica: il rifiuto per Broken Functionality illustra la notifica di funzionalità più comune. Non ricostruire la tua TWA come WebView solo a causa di una barra del browser. Se la tua app è nata da un builder AI, pubblicare un’app vibe-coded su Google Play copre l’intero percorso dal progetto a Play.

Domande frequenti

In sintesi

Le etichette dei menu di Play Console sono il dato che cambia più in fretta in questa pagina. Se i percorsi qui sopra non corrispondono più alla tua Console, cerca Play app signing in Protected with Play, oppure cerca app signing nella Console.