KappS Wissensdatenbank · Blog

Android App-Links 2026: Prüfung in Schritten

Blog Tutorial

Ein Android App Link ist der einzige Deep-Link-Mechanismus, den Google als Eigentumsnachweis akzeptiert: Ihre App deklariert einen HTTPS-Host, den sie verarbeiten möchte, veröffentlicht eine Digital Asset Links-Erklärung auf diesem Host, und Android prüft, ob beide übereinstimmen, bevor Ihre App statt des Browsers geöffnet wird. Zwei Artefakte entscheiden über das Ergebnis – eine /.well-known/assetlinks.json-Datei, die Sie kontrollieren, und der darin enthaltene SHA-256-Signatur-Fingerabdruck –, und die meisten Fehlschläge entstehen dadurch, dass eines davon leicht falsch ist, nicht durch etwas Exotisches.

Dieses Tutorial folgt der Reihenfolge, in der die Arbeit tatsächlich abläuft: den autoVerify-Intent-Filter deklarieren, die assetlinks.json-Statement-Liste veröffentlichen, den richtigen Fingerprint wählen, wenn Play App Signing Ihren Build neu signiert, den Verifizierungsstatus installieren und auslesen, die in der Produktion häufigen Fehler diagnostizieren, einen Fallback entwerfen, der Nutzer nicht belügt, und die App-Link-Verifizierung über Schlüsselrotationen und Domainwechsel hinweg am Leben halten. Die Regel dahinter: Verifizierung ist ein Versprechen, dass Domain und App denselben Eigentümer haben – der einzige legitime Weg, sie zu bestehen, ist also, tatsächlich beide zu besitzen.


1. Was ein verifizierter Link belegt — und was nicht

Drei Ideen werden vermischt, und ihre Trennung verhindert die meisten schlechten Designentscheidungen.

  • Ein Deep Link ist jeder Intent, der einen Screen innerhalb Ihrer App öffnet. Er kann aus einem eigenen Schema wie myapp://product/42 stammen, das jede App auf dem Gerät registrieren darf – eine bösartige App kann dasselbe Schema beanspruchen und die URL statt Ihnen empfangen.
  • An App Link is an HTTPS URL — https://shop.example.com/product/42 — that Android has verified you are entitled to handle, because that host publishes a statement naming your package and your signing certificate. The user sees a normal web URL, the browser can always open it, and only one app can win the verification.
  • Ein Web-Fallback ist dieselbe URL, die im Browser geöffnet wird, wenn Ihre App nicht installiert ist. Eine gut aufgebaute Link-Strategie bringt alle drei Komponenten in Einklang, sodass die URL den gewünschten Inhalt auflöst – unabhängig davon, ob die App vorhanden ist.

Was die Verifizierung nicht leistet: Sie beweist nicht, dass die App installiert ist, sie gewährt Ihnen keine Rechte an den Inhalten der Domain, und sie ersetzt keine Authentifizierung. Wenn ein Bildschirm Kontodaten anzeigt, schützt sie nach wie vor die Token-Prüfung auf dem Server. Die Verifizierung beantwortet nur „darf diese App Links für diesen Host öffnen" — mehr nicht.

Eine praktische Konsequenz: Behalten Sie benutzerdefinierte Schemata höchstens für interne Übergaben bei und verlassen Sie sich niemals auf sie für Passwort-Zurücksetzungen oder Zahlungsweiterleitungen, denn die Eigentümerschaft eines Schemas ist nicht durchsetzbar.

2. Schritt 1 — autoVerify-Intent-Filter im Manifest deklarieren

Beginnen Sie in AndroidManifest.xml. Der Filter muss ein https-Filter mit android:autoVerify="true" sein und benötigt die Aktion VIEW sowie sowohl die Kategorien DEFAULT als auch BROWSABLE:

<intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" android:host="shop.example.com" /> </intent-filter>

Details, die entscheiden, ob das in der Praxis funktioniert:

  • Ein Filter pro Host. Die Verifizierung wird pro Host bewertet, und die Empfehlung von Google ist ein separater <intent-filter> für jede Domain. Fassen Sie fünf Hosts in einem Filter zusammen, vergiftet ein einziger fehlerhafter Host die übrigen.
  • Hosts sind wörtlich zu nehmen. android:host akzeptiert keine Platzhalter. Erreichen Sie Subdomains mit separaten Filtern und grenzen Sie den Bereich mit android:path, android:pathPrefix oder android:pathPattern ein, damit die App keine URLs beansprucht, die sie nicht darstellen kann.
  • http ist nicht verifizierbar. Nur https nimmt an der automatischen Verifizierung teil. Einen http-Filter beizubehalten, erzeugt nur doppelte Auswahlaufforderungen.
  • Beanspruchen Sie nur, was Sie weiterleiten. Ein Filter, der den gesamten Host abdeckt, während die App drei Pfade verarbeitet, schickt jede andere URL auf einen leeren Bildschirm – und dieses Verhalten zeigt sich in Store-Bewertungen lange bevor es in Ihrem Absturz-Dashboard auftaucht.

Wenn Ihre App sowohl eine Marketing-Domain als auch eine App-Domain verwendet, entscheiden Sie bewusst, welche für das Teilen kanonisch ist. Jeder Host, den Sie hinzufügen, ist eine Datei zum Veröffentlichen und ein Zertifikat, das synchron gehalten werden muss.

3. Schritt 2 — veröffentlichen Sie /.well-known/assetlinks.json

Die Umsatzliste liegt unter genau einem Pfad, über HTTPS und ohne vorgeschaltete Weiterleitung:

https://shop.example.com/.well-known/assetlinks.json

Der Body ist ein JSON-Array aus Statements. Für eine gewöhnliche App, die alle URLs auf dem Host verarbeitet, genügt ein Statement:

[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.shop", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] } }]

Mehrere Pakete oder ein Paket mit mehreren Zertifikaten fügen demselben Array einfach weitere Einträge hinzu. Die Details der Auslieferung zählen ebenso wie der Inhalt:

  • Inhaltstyp. Liefern Sie ihn als application/json aus. Einige Android-Versionen und einige CDN-Edge-Konfigurationen sind hier streng.
  • Keine Weiterleitungen. Ein 301 oder 302 vor der Datei führt dazu, dass der Abruf fehlschlägt — und das Scheitern bleibt auf dem Gerät unbemerkt. Das ist der häufigste Hosting-Fehler — eine websiteweite Regel wie „HTTPS erzwingen“ oder „abschließenden Schrägstrich entfernen“ bricht ihn unbemerkt.
  • Keine Authentifizierung, keine Bot-Sperre. Der Verifier von Google ruft die Datei anonym ab. Eine WAF-Herausforderung oder ein Geo-Block liefert eine HTML-Fehlerseite, wo JSON erwartet wird.
  • Gültiges JSON, keine Kommentare. Ein nachgestelltes Komma oder ein verirrter //-Kommentar macht die ganze Datei ungültig und jede Aussage darin.

Before you debug anything on the device, fetch the file the way the verifier would: curl -sI https://shop.example.com/.well-known/assetlinks.json should show 200 and no Location header, and the body should parse. Google publishes a statement list generator and tester that will validate the structure and the fingerprint format for you — use it before shipping.

4. Schritt 3 — den Fingerprint verwenden, den das Gerät tatsächlich sieht

Hier scheitert der Großteil der Verifizierungen, und der Grund ist Play App Signing. Wenn Sie sich anmelden, hält Google den App-Signaturschlüssel und signiert jedes ausgelieferte Artefakt neu. Das auf dem Gerät eines Nutzers installierte Zertifikat ist daher das App-Signaturzertifikat — nicht der Upload-Schlüssel auf Ihrem Build-Rechner.

  • Play-Installationen benötigen das SHA-256-Zertifikat des App-Signaturschlüssels, das Sie in der Play Console unter App-Integrität → App-Signierung finden (der Block „App signing key certificate").
  • Lokale und per Sideload installierte Builds werden mit Ihrem Upload- oder Debug-Schlüssel signiert und benötigen diesen Fingerabdruck — lesen Sie ihn mit keytool -list -v -keystore <keystore> aus und kopieren Sie die SHA-256-Zeile.
  • Reichen Sie beides ein. Das Signaturzertifikat der App und das Upload-Zertifikat im selben sha256_cert_fingerprints-Array aufzuführen, ist normal und erwartet; so können Play-Installationen verifiziert werden, während Ihre QA-Builds weiter funktionieren.

Zwei weitere Fallstricke im selben Bereich. Wenn Sie einen Debug-Keystore verwenden, ist sein Fingerabdruck spezifisch für die Maschine, die ihn erzeugt hat — gut für Ihre eigenen Tests, nutzlos in der veröffentlichten Datei. Und wenn Sie jemals das Schlüssel-Upgrade von Play nutzen, ändert sich das Zertifikat: Die Statement-Liste muss vor dem Rollout des Upgrades aktualisiert werden, sonst brechen Links für Neuinstallationen, während alte weiter funktionieren.

Kopieren Sie die Fingerprints aus der Konsole, statt sie abzutippen. Ein einziges vertauschtes Hexadezimalpaar erzeugt eine Datei, die gültiges JSON ist, mit 200 ausgeliefert wird und die Verifizierung trotzdem ohne Fehlermeldung an irgendeiner Stelle nicht besteht.

5. Schritt 4 — installieren und den tatsächlichen Verifizierungsstatus auslesen

Die Verifizierung wird bei der Installation der App versucht und erneut nach Updates, daher müssen Sie die App aus dem Kanal installiert haben, den Sie testen — eine Installation über den internen Test von Play verhält sich anders als ein adb install eines upload-signierten Builds.

Ab Android 12 und höher fragen Sie die Plattform direkt ab:

adb shell pm get-app-links com.example.shop

Sie erhalten einen Bericht pro Domain: die Domain, ob der Nutzer sie genehmigt hat und der Prüfstatus — verified, wenn die Erklärungsliste übereinstimmte, denied oder legacy_failure, wenn nicht. Bei älteren Releases entspricht dem ein Dump der Domain-Verifizierungseinträge:

adb shell dumpsys package d

Wird ein Host als verweigert angezeigt und Sie haben die Datei gerade erst korrigiert, erzwingen Sie einen frischen Versuch, statt blind neu zu installieren:

adb shell pm set-app-links --package com.example.shop --domain shop.example.com all

Testen Sie dann den Ablauf, den ein Nutzer durchläuft. Ein im Browser eingegebener Link, ein in einem Mail-Client angetippter Link und ein Link innerhalb einer anderen App werden nicht immer gleich aufgelöst, und nur einer davon führt möglicherweise über den Auswahldialog. Prüfen Sie außerdem den Bildschirm Standardmäßig öffnen in den Systemeinstellungen: Ein Nutzer kann einen verifizierten Link deaktivieren, und Ihr Code sollte das ohne Fehler überstehen.

6. Schritt 5 — diagnostizieren Sie die Fehler, die Sie tatsächlich treffen werden

Fast jeder Produktionsfehler fällt in eine von fünf Kategorien. Prüfen Sie sie in dieser Reihenfolge; jede dauert Sekunden.

  1. Falscher Fingerabdruck. Die Datei lässt sich parsen, der Host stimmt, und das Zertifikat in der Erklärung ist der Upload-Schlüssel, während das Gerät den Play-signierten Build enthält. Vergleichen Sie den Fingerabdruck in der Konsole Zeichen für Zeichen mit der Datei.
  2. Weiterleitung oder falscher Inhaltstyp. curl -sI zeigt einen 3xx, text/html oder eine CDN-gecachte Fehlerseite. Korrigieren Sie den Header, leeren Sie den Cache und prüfen Sie dann erneut.
  3. Paketname oder Host stimmen nicht überein. Eine Application ID wurde für einen White-Label-Build geändert, oder ein Filter listet noch einen Staging-Host, der die Datei nicht mehr ausliefert. Durchsuchen Sie das Manifest nach jedem Host und bestätigen Sie, dass jeder eine aktive Erklärung hat.
  4. Die Verifizierung wurde nie ausgeführt. Die Installation erfolgte offline, oder die App wurde seit der Installation nie gestartet. Öffnen Sie die App einmal mit Verbindung und führen Sie dann pm get-app-links erneut aus.
  5. Nutzer-Override. Die Domain wurde in den Einstellungen deaktiviert — manchmal Monate zuvor, manchmal durch ein OEM-Migrationstool. pm set-app-links … all setzt sie zum Testen zurück; für echte Nutzer ist Aufklärung die Lösung, nicht Zwang.

Halten Sie einen einzeiligen Smoke-Test in Ihrer Release-Checkliste: die Datei abrufen, sie parsen und prüfen, dass der Fingerprint dem entspricht, den die Konsole aktuell anzeigt. Ein Domainwechsel oder ein Schlüssel-Upgrade, das diese Prüfung überspringt, ist genau der Weg, auf dem ein funktionierendes Link-Setup still und leise stirbt.

7. Schritt 6 — bauen Sie einen Fallback, der die Wahrheit sagt

App Links machen die App zum bevorzugten Handler; sie machen sie nicht zum einzigen. Gestalten Sie zuerst die Webseite, denn dieser Fall besteht immer.

  • Die URL muss ohne die App rendern. Ein Share-Link, der nur bei installierter App funktioniert, ist ein defekter Link und bricht auch die Crawler, die ihn indexieren.
  • Erkennen, dann anbieten — nicht kapern. Ein kleines Banner mit „In App öffnen" und einem Store-Link konvertiert besser als eine automatische Weiterleitung, die Nutzer fängt, die bewusst den Browser wollen.
  • Halten Sie den Deep-Link-Pfad identisch zum Web-Pfad. Wenn die App /product/42 rendert, sollte die Webseite unter demselben Pfad dasselbe Produkt zeigen; die Zuordnungstabelle, die Sie vermeiden aufzubauen, ist genau die, die im nächsten Quartal brechen wird.
  • Behandeln Sie den Fall der ausstehenden Installation. Deferred Deep Linking — bei dem ein neuer Nutzer die App installiert und auf dem geteilten Element landet — erfordert einen serverseitigen Mechanismus oder einen Install-Referrer. Firebase Dynamic Links, das Tool, das die meisten Teams dafür nutzten, wurde eingestellt, planen Sie also die Install Referrer API oder ein eigenes Äquivalent ein, statt einen gehosteten Dienst vorauszusetzen.

Und widerstehen Sie der Versuchung, die Verifizierung unsichtbar zu machen. Wenn die App eine URL nicht rendern kann, ist es besser, den Browser damit zu betrauen, als einen app-seitigen „Nicht gefunden“-Bildschirm zu zeigen – und das SEO der Domain bleibt intakt.

8. Die Verifizierung über Releases und Domains hinweg aufrechterhalten

Die Verifizierung ist kein einmaliges Setup. Sie ist eine dauerhafte Übereinkunft zwischen drei beweglichen Teilen: dem Manifest, der veröffentlichten Datei und dem Zertifikat, mit dem der Store tatsächlich signiert. Alles, was eines davon berührt, gehört auf die Release-Checkliste.

  • Wichtiges Upgrade oder erneute Signierung. Aktualisieren Sie assetlinks.json mit dem neuen Zertifikat und veröffentlichen Sie es vor dem Rollout; lassen Sie das alte dann aufgeführt, bis die vorherige Version vollständig abgelöst ist.
  • Domainwechsel. Veröffentlichen Sie die Aussagen zuerst auf dem neuen Host und bringen Sie die Manifest-Änderung erst danach an. Ein Filter, der auf einen Host ohne Datei zeigt, nimmt Links sofort offline.
  • Marken- und regionale Domains. Jeder Host ist eine eigene Erklärung und eine eigene Datei. Automatisieren Sie das Deployment, damit eine neue regionale Domain nicht ohne sie live gehen kann.
  • Eigentumsprüfungen. Die Datei ist eine öffentliche Erklärung, dass Sie die Domain kontrollieren. Veröffentlichen Sie sie nur für Domains, die Ihre Organisation besitzt und betreibt, und hosten Sie niemals die Erklärung eines Dritten für diesen — genau dieses Muster sucht die Missbrauchserkennung, und es gefährdet sowohl die Domain als auch das App-Konto.

Bewahren Sie die Manifest-Filter, die veröffentlichte JSON-Vorlage und die aktuellen Fingerprints an einer Stelle auf, generiert aus einer einzigen Quelle der Wahrheit. Wenn es drei getrennte manuelle Bearbeitungen sind, driften sie innerhalb von zwei Release-Zyklen auseinander.

9. Wo KappS passt

Wir arbeiten auf der operativen Seite des Auslieferns: Konten, Releases und Store-Datensätze in einem Zustand halten, der einer Plattformprüfung standhält — konformes Material vorbereiten und einreichen, niemals eine Prüfung umgehen. Bei der Link-Verifizierung bedeutet das in der Regel:

  • Release-Hygiene. Zertifikate und Anwendungs-IDs stimmen zwischen Konsole, Build und veröffentlichter Statement-Liste überein, sodass der Fingerabdruck, den das Gerät sieht, dem dokumentierten entspricht.
  • Kontobereitschaft. Entwicklerprüfung, Zahlungsprofil und Steuerangaben abgestimmt auf den Rechtsträger hinter dem Konto, damit ein Launch nicht durch eine unabhängige Prüfung ins Stocken gerät.
  • Prüfung von Domain und Hosting. Kontrolle, ob der Well-Known-Pfad tatsächlich JSON ausliefert, ohne Weiterleitungen, ohne WAF-Challenge und ohne zwischengeschaltete Fehlerseite aus dem Cache.

Was wir nicht tun: Erklärungen für Domains veröffentlichen, die ein Kunde nicht besitzt, einen Fingerprint fälschen oder einer App helfen, einen Host zu beanspruchen, auf den sie kein Recht hat. Verifizierung existiert, um Nutzer genau davor zu schützen, und das ist keine Leistung, die wir anbieten.

Quellen (offizielle Dokumentation): Android Developers — Verify Android App Links; Add Android App Links; Digital Asset Links specification; Play Console Help — App signing key certificate and key upgrade; Android Developers — Adb shell pm commands for app links.

Sie verwalten Entwicklerkonten im großen Stil? Wir übernehmen die operative Seite.

Klicken Sie, um eine Datei auszuwählen · Rechtsklick → Einfügen oder Ctrl/⌘+V drücken, um einen Screenshot einzufügen

Sie können eine Datei auch auf dieses Feld ziehen.

Wir antworten an die von Ihnen angegebene E-Mail-Adresse. Ihre Daten bleiben bei KappS.

✔ Eingereicht

Wir haben Ihre Nachricht erhalten und antworten innerhalb von 24 Stunden.


← Zurück zum Bearbeiten