assetlinks.json SHA-256 nach Play App Signing: Browserleiste der TWA beheben

Dieser Leitfaden behandelt eine einzige Reparatur: die Verknüpfung zwischen Ihrer Website und dem Build, den Google Play ausliefert. Er behandelt weder den Bau der TWA selbst noch die Überprüfung der App durch Play; dafür gibt es eigene Leitfäden, die weiter unten verlinkt sind. Jede hier zitierte Google-Seite wurde am 16. Oktober 2026 geprüft, die Quellen stehen am Ende.

Warum die Browserleiste nur bei der Play-Installation erscheint

Chrome verifiziert eine TWA, indem es das Zertifikat, mit dem die installierte App signiert wurde, mit den Fingerabdrücken vergleicht, die Ihre Website veröffentlicht. Schlägt diese Prüfung fehl, zeigt der Browser laut Chromes TWA-Schnellstart Ihre Website ersatzweise als Custom Tab an. Dieser Ersatz ist die Adressleiste, die Sie sehen.

Mit Play App Signing gibt es in der Regel zwei Zertifikate. Sie signieren das hochgeladene Bundle mit Ihrem Upload-Schlüssel, und Google signiert die ausgelieferten APKs mit dem App-Signaturschlüssel. Chromes Seite Android concepts for web developers sagt, dass der Fingerabdruck des App-Signaturschlüssels derjenige ist, der Ihrer App entspricht, wenn sie aus dem Play Store heruntergeladen wird. Eine Datei, die nur Ihr lokales Zertifikat enthält, besteht die Prüfung daher an Ihrem Schreibtisch und scheitert auf jedem Smartphone, auf dem die App aus Play installiert wurde.

Die beiden Schlüssel sind nicht immer verschieden. Die Android-Dokumentation zur App-Signatur beschreibt Konfigurationen, in denen derselbe Schlüssel sowohl als App-Signaturschlüssel als auch als Upload-Schlüssel dient. Die Lösung besteht also darin, die tatsächlichen Zertifikate zu vergleichen, statt anzunehmen, welches Sie haben.

Den SHA-256 der App-Signatur in der Play Console finden

Googles eigene Dokumentation nennt derzeit zwei Bezeichnungen für dieselbe Stelle. Beide beginnen bei Protected with Play im linken Menü Ihrer App.

Ältere Anleitungen, darunter einige Google-Seiten, nennen noch Release > Setup > App signing oder Setup > App integrity. Wenn Sie nur diese Bezeichnungen finden, suchen Sie dieselbe Seite unter einem älteren Namen.

Den Fingerabdruck eines eigenen Schlüssels auslesen

Für Ihren Upload-Schlüssel oder einen Debug-Schlüssel gibt Javas keytool dasselbe Format aus. Ersetzen Sie Keystore-Datei und Alias durch Ihre eigenen und kopieren Sie dann die Zeile mit der Bezeichnung SHA256:

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

Wenn Sie viele Apps verwalten, kann auch die Google Play Developer API den Zertifikats-Hash der von Play generierten APKs liefern (das Feld certificateSha256Hash in der Liste der generierten APKs). Für eine einzelne Korrektur ist das Kopieren aus der Play Console einfacher.

Eine korrekte assetlinks.json schreiben und ausliefern

Die Datei ist ein JSON-Array aus Anweisungen. Bei einer TWA lautet die Relation delegate_permission/common.handle_all_urls, und das Ziel ist Ihre Android-App: der Namespace android_app, Ihre exakte Anwendungs-ID und ein Array von SHA-256-Fingerabdrücken. Eine minimale Datei sieht so aus:

[
  {
    "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"
      ]
    }
  }
]

Ersetzen Sie com.example.twa durch Ihre Anwendungs-ID und jeden Platzhalter durch einen vollständigen, durch Doppelpunkte getrennten SHA-256. Löschen Sie den zweiten Eintrag, wenn nur Play-Installationen verifiziert werden müssen. Nur striktes JSON: keine Kommentare, keine abschließenden Kommas, keine SHA-1-Werte.

Wie Google die Auslieferung der Datei verlangt

• Exakter Speicherort. https://your-domain/.well-known/assetlinks.json, mit dem Punkt in .well-known. example.com und www.example.com sind verschiedene Ursprünge; veröffentlichen Sie die Datei auf jedem, den Ihre App öffnet. Eine Kopie in einem Unterverzeichnis wie /app/.well-known/ zählt nicht.
• Ein direktes HTTP 200. Googles Dokumentation zu Digital Asset Links sagt: “Jede andere Antwort des Servers als HTTP 200 wird als Fehler behandelt und führt zu einer leeren Anweisungsliste.”
• Keine Weiterleitungen. Antworten mit 301 und 302 werden nicht verfolgt. Das schließt einen Sprung von http zu https und von der nackten Domain zu www ein.
• HTTPS mit gültiger Zertifikatskette und der Header Content-Type: application/json. Eine Anmeldeseite oder eine HTML-Fehlerseite, die mit 200 antwortet, ist keine gültige Datei.

Prüfen Sie die Live-Antwort in einem beliebigen Terminal. Die erste Statuszeile muss 200 lauten und der Content-Type muss JSON sein, ohne vorangehendes 3xx:

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

Mehr als ein Fingerabdruck, mehr als eine App

Der Android-Leitfaden zur Website-Verknüpfung sagt über das Fingerabdruck-Array: “Dieses Feld unterstützt mehrere Fingerabdrücke, mit denen sich verschiedene Versionen Ihrer App unterstützen lassen, etwa Debug- und Produktions-Builds.” Fügen Sie einen Upload- oder Debug-Fingerabdruck nur für Builds hinzu, denen diese Website tatsächlich vertrauen soll. Ein Build mit einer anderen Anwendungs-ID, etwa ein separates Debug-Paket, braucht eine eigene Anweisung im Array.

Wenn Sie die TWA mit Bubblewrap oder PWABuilder erstellt haben

Fügen Sie in einem bestehenden Bubblewrap-Projekt den Fingerabdruck von Play hinzu und generieren Sie die Datei neu:

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

Die Datei zu generieren heißt nicht, sie zu deployen: Laden Sie die neue assetlinks.json auf Ihre Website hoch und prüfen Sie sie mit curl. bubblewrap validate prüft Ihre PWA anhand von Qualitätskriterien; die Signaturverknüpfung prüft es nicht, ein bestandener Lauf beweist also nichts über den Fingerabdruck. Die aktuelle Anleitung von PWABuilder sagt zur Signatur dasselbe, “Sobald Sie Ihre .aab-Datei hochgeladen haben, signiert Google Play Ihre App neu”, und weist Sie an, den Fingerabdruck von Play in die generierte Datei einzutragen. Eine Korrektur des Fingerabdrucks ist eine Änderung an Ihrer Website, nicht am App-Binary.

Die Verknüpfung prüfen, dann die Play-Installation testen

Vier Ebenen sind beteiligt: die Datei auf Ihrer Website, Googles Digital Asset Links API, Androids eigene Link-Verifizierung und der Browser, der Ihre TWA startet. Wer eine Ebene besteht, hat die nächste noch nicht bestanden. Prüfen Sie sie deshalb der Reihe nach und schließen Sie mit dem Gerät ab.

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

Der App Links Assistant von Android Studio (Tools > App Links Assistant) prüft die Verknüpfung für Android App Links und Ihr Manifest. Dafür ist er nützlich, aber er sagt Ihnen nicht, ob Ihre TWA im Vollbild startet; das zeigt nur der Test auf dem Gerät.

Für Fortgeschrittene: Androids eigener Verifizierungsstatus

Für Android 12 und höher dokumentiert Androids Verifizierungsleitfaden diese Befehle für App Links. Ersetzen Sie das Paket, führen Sie die ersten beiden aus, warten Sie einige Minuten und lesen Sie dann den Status aus:

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 beschreibt Androids Domainverifizierung, nicht, ob Ihre TWA ohne Browseroberfläche startet. Codes ab 1024 sind verifiziererspezifische Fehler, keine Diagnose eines falschen SHA-256. Für die TWA selbst verwenden Sie das Chrome-Protokoll von oben.

Der Fingerabdruck stimmt, aber die Leiste bleibt

Eine sichtbare Leiste beweist nicht, dass der SHA-256 falsch ist. Wenn die Prüfung oben linked: true liefert und die Leiste trotzdem da ist, gehen Sie diese Ursachen durch.

Wie lange es dauert, bis eine korrigierte Datei wirkt

Google nennt für TWAs keine einheitliche Wartezeit, weil mehrere Caches beteiligt sind und jeder eigene Regeln hat:

• Ihr Server oder CDN liefert möglicherweise noch die alte Datei aus. Leeren Sie den Cache und bestätigen Sie die Live-Antwort mit curl.
• Die Digital Asset Links API gibt im Feld maxAge an, wie lange jede Antwort gültig bleibt.
• Android App Links folgt einem eigenen Zeitplan. Androids Verifizierungsleitfaden sagt, dass Änderungen unter Android 15 und höher bis zu sieben Tage brauchen können, bis sie alle Geräte erreichen, und dass die Datei unter Android 14 und niedriger in der Regel bei der Installation oder Aktualisierung der App abgerufen wird.
• Der Browser behält möglicherweise einen eigenen Zustand. Ein Entwickler berichtete von Erfolg, nachdem er die Daten von Chrome gelöscht hatte.

Leeren Sie also den Cache, bestätigen Sie die Live-Datei und installieren Sie die App erneut aus Google Play. Auf einem Testgerät können eine Neuinstallation oder das Löschen der Browserdaten einen zwischengespeicherten Zustand ausschließen; das ist ein Diagnoseschritt, nichts, worum Sie jeden Nutzer bitten sollten. Planen Sie nicht mit einer festen Anzahl von Stunden.

Ablehnung, Überprüfung und geschlossener Test

Eine fehlende oder falsche assetlinks.json ist für sich allein nicht als Ablehnungsgrund dokumentiert. Was die Dokumentation beschreibt, ist der Rückfall auf einen Custom Tab mit Browseroberfläche. Die Überprüfung ist eine andere Frage: Die Funktionalitätsrichtlinie von Google Play sagt “Apps, die abstürzen, das Schließen erzwingen, einfrieren oder anderweitig nicht ordnungsgemäß funktionieren, sind nicht zulässig”, und das gilt unabhängig vom Status Ihrer Verknüpfung. Ein korrekter Fingerabdruck behebt die Leiste; über die Überprüfung entscheidet er nicht. Wenn Sie eine Ablehnung erhalten haben, gehen Sie von der Richtlinie aus, die in der E-Mail genannt wird.

Einige ältere Artikel behaupten, Chrome lasse eine TWA abstürzen, die ihre Qualitätsprüfungen nicht besteht. Chromium hat diesen QualityEnforcer-Code am 4. Mai 2023 entfernt. Betrachten Sie diesen Rat also als historisch und nicht als Beschreibung heutiger Browser.

Wenn Sie eine Ablehnung erhalten haben, arbeiten Sie mit dem Grund aus der Benachrichtigung: Die Ablehnung wegen Broken Functionality geht die häufigste Benachrichtigung zur Funktionalität Schritt für Schritt durch. Bauen Sie Ihre TWA nicht allein wegen einer Browserleiste als WebView neu. Wenn Ihre App aus einem KI-Builder stammt, beschreibt eine Vibe-Coding-App bei Google Play veröffentlichen den gesamten Weg vom Projekt bis zu Play.

Häufig gestellte Fragen

Das Fazit

Die Menübezeichnungen der Play Console sind die Fakten auf dieser Seite, die sich am schnellsten ändern. Wenn die Wege oben nicht mehr zu Ihrer Console passen, suchen Sie Play App Signing unter Protected with Play oder suchen Sie in der Console nach App-Signatur (app signing).