Websitezuordnungen und dynamische Regeln konfigurieren

Damit App-Links unterstützt werden, müssen Sie eine Digital Asset Links-JSON-Datei mit dem Namen assetlinks.json erstellen und an einem bekannten Ort auf Ihrer Website veröffentlichen. In dieser Datei wird öffentlich deklariert, welche Apps berechtigt sind, Links für Ihre Domain zu verarbeiten. Android-Geräte rufen diese Datei von Ihrem Server ab, um Ihre Deeplinks zu überprüfen.

Bei dynamischen App-Links in Android 15 oder höher ist die Datei assetlinks.json auch der Ort, an dem Sie die Konfiguration Ihrer dynamischen Regeln definieren, z. B. Musterabgleiche für Pfad-, Fragment- und Suchparameter. Android-Geräte mit Android 15 (API-Level 35) oder höher, auf denen Google-Dienste installiert sind, rufen die Datei regelmäßig ab und führen Ihre dynamische Konfiguration mit der statischen Konfiguration im Manifest der App zusammen.

In diesem Leitfaden wird beschrieben, wie Sie eine assetlinks.json-Datei vorbereiten und auf Ihrer Website veröffentlichen. Wenn Sie möchten, können Sie eine assetlinks.json-Datei mit dem Tool „Play-Deeplinks“ oder dem App-Link-Assistenten von Android Studio generieren. Weitere Informationen finden Sie unter Entwicklertools für App-Links.

Websiteverknüpfungen deklarieren

Sie müssen eine Digital Asset Links-JSON-Datei auf Ihrer Website veröffentlichen, um die Android-Apps anzugeben, die mit der Website verknüpft sind, und die URL-Intents der App zu bestätigen. In der JSON-Datei werden die folgenden Felder verwendet, um verknüpfte Apps zu identifizieren:

  • package_name: Die Anwendungs-ID, die in der Datei build.gradle der Anwendung deklariert ist.
  • sha256_cert_fingerprints: Die SHA256-Fingerprints des Signaturzertifikats Ihrer App. Mit dem folgenden Befehl können Sie den Fingerabdruck mit dem Java-Keytool generieren:

keytool -list -v -keystore my-release-key.keystore

  • Dieses Feld unterstützt mehrere Fingerabdrücke, die für verschiedene Versionen Ihrer App verwendet werden können, z. B. Debug- und Produktions-Builds. Wenn Sie die Play App-Signatur für Ihre App verwenden, stimmt der Zertifikat-Fingerabdruck, der durch die lokale Ausführung von keytool erzeugt wird, in der Regel nicht mit dem auf den Geräten der Nutzer überein. In Ihrem Play Console-Entwicklerkonto können Sie unter Release > Setup > App signing prüfen, ob Sie die Play App-Signatur für Ihre App verwenden. Wenn ja, finden Sie auf derselben Seite auch das richtige JSON-Snippet für Digital Asset Links für Ihre App.

In der folgenden assetlinks.json-Beispieldatei werden einer Android-App mit dem Paketnamen com.example Rechte zum Öffnen von Links gewährt:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "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"]
  }
}]

Website mit mehreren Apps verknüpfen

Eine Website kann in derselben assetlinks.json-Datei Verknüpfungen mit mehreren Apps deklarieren. Die folgende Dateiauflistung zeigt ein Beispiel für eine Anweisungsdatei, die die Verknüpfung mit zwei Apps separat deklariert und sich unter https://www.example.com/.well-known/assetlinks.json befindet:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "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"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "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"]
  }
}]

Verschiedene Apps können Links für verschiedene Ressourcen unter demselben Webhost verarbeiten. Beispielsweise kann app1 einen Intent-Filter für https://example.com/articles und app2 einen Intent-Filter für https://example.com/videos deklarieren.

Mehrere Websites mit einer einzelnen App verknüpfen

Mehrere Websites können in ihren jeweiligen assetlinks.json-Dateien Verknüpfungen mit derselben App deklarieren. Die folgenden Dateilisten zeigen ein Beispiel dafür, wie die Verknüpfung von beispiel.de und beispiel.net mit app1 deklariert wird. Der erste Eintrag zeigt die Verknüpfung von example.com mit app1:

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

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "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"]
  }
}]

Die nächste Auflistung zeigt die Verknüpfung von example.net mit app1. Nur der Speicherort, an dem diese Dateien gehostet werden, ist unterschiedlich (.com und .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "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"]
  }
}]

Dynamische Regeln konfigurieren

Mit dynamischen App-Links in Android 15 und höher können Sie serverseitige Deeplink-Abgleichsregeln verwenden, die mit den Regeln zusammenarbeiten, die Sie statisch in Ihrem App-Manifest definiert haben. In der Datei assetlinks.json definieren Sie dynamische Regeln. Diese Angabe ist optional.

Android-Geräte mit Android 15 (API-Level 35) oder höher, auf denen Google-Dienste installiert sind, rufen diese Datei regelmäßig von Ihrem Server ab und führen die Konfiguration der dynamischen Regeln mit der statischen Konfiguration im Manifest der App zusammen. Im Folgenden finden Sie ein Beispiel für eine assetlinks.json-Datei mit dynamischen Regeln:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Wichtige Punkte zum Code

  • Mit dynamischen App-Links wird eine neue Digital Asset Links-Beziehungserweiterung namens dynamic_app_link_components hinzugefügt, in der Sie Ihre dynamischen Regeln konfigurieren.
  • Dynamische Regeln können Musterabgleiche für Pfad-, Fragment- und Suchparameter enthalten.
  • Sie können auch einen beliebigen Musterabgleich als ausgeschlossen markieren, damit übereinstimmende URLs Ihre App nicht öffnen.
  • In diesem Beispiel werden Abgleiche für Pfad ("/"), Fragment ("#") und Suchparameter ("?") sowie ausgeschlossene Abgleiche ("exclude") gezeigt.
  • Wenn eines der Felder in der Datei fehlerhaft oder leer ist, verwirft Android die dynamischen Regeln und das Gerät greift auf die Regeln zurück, die statisch im Manifest der App definiert sind.

Mit dynamischen Regeln können nur Regeln angegeben werden, die im Rahmen der Domains gelten, die Sie in der Manifestdatei Ihrer App deklarieren. Weitere Informationen finden Sie im Abschnitt Dynamische Regeln deklarieren.

Dynamische Regeln deklarieren

Dynamische App-Links unterstützen eine neue dynamic_app_link_components-Beziehungserweiterung, die ein Array von Regelobjekten enthält. Jede Regel wird mithilfe von Mustern für Pfade, Fragmente und Suchparameter definiert, die Ihre App öffnen. Muster können auch einzeln ausgeschlossen werden, damit sie Ihre App nicht öffnen. Alle diese Angaben sind optional.

  • Pfadabgleich
    • Taste: „/“
    • Wert: Einzelner String, übereinstimmender Ausdruck für den URL-Pfad
  • Fragmentabgleich
    • Taste: „#“
    • Wert: Einzelner String, übereinstimmender Ausdruck für das URL-Fragment
  • Abgleich von Suchparametern
    • Taste: „?“
    • Wert: Dictionary zum Abgleich von Schlüssel/Wert-Paaren in den URL-Suchparametern.
    • Beispielsweise stimmt das Wörterbuch {"?", {"dl": "*", "in_app":"true"} mit dem Abfragestring "?in_app=true&dl=abc" überein.
    • Die Reihenfolge der Schlüssel/Wert-Paare im Dictionary muss nicht mit der Reihenfolge der Paare im Abfragestring übereinstimmen. Außerdem muss das Dictionary nicht mit allen Schlüssel/Wert-Paaren im Abfragestring übereinstimmen, aber für jeden Dictionary-Eintrag muss eine Übereinstimmung gefunden werden.
    • Das Wörterbuch würde beispielsweise auch mit dem Abfragestring „?lang=en&in_app=true&tz=pst&dl=abc“ übereinstimmen, aber nicht mit dem Abfragestring „?lang=en&tz=pst&dl=abc“.
  • Ausgeschlossen
    • Schlüssel: „exclude“
    • Wert: Optionaler Wahr/Falsch-Wert für jede in dynamic_app_link_components definierte Regel (siehe Beispiel).

Sie können die folgenden Sonderzeichen in Musterabgleichen verwenden:

  • „*“ entspricht null oder mehr Zeichen, bis das Zeichen nach dem Platzhalter im Muster im übereinstimmenden String gefunden wird.
  • „?“ entspricht einem einzelnen Zeichen.
  • „?*“ entspricht einem oder mehreren Zeichen.

Es gibt keine weiteren Zeichenbeschränkungen für Werte.

Dynamische Regeln sortieren

Die Reihenfolge, in der die Regeln deklariert werden, ist wichtig. Android wertet jede Regel der Reihe nach aus, bis eine Übereinstimmung gefunden wird.

Das folgende Beispiel zeigt, wie sich die Reihenfolge auf die Verarbeitung auswirken kann. Die erste Regel stimmt mit allen Pfaden („*“) überein, schließt aber Übereinstimmungen aus (exclude: true). Das bedeutet, dass alle URLs vom Öffnen der App ausgeschlossen werden. In diesem Fall wird die zweite Regel, die „/path1“ zulässt, nie ausgewertet.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

Im nächsten Beispiel wird die Regel „/path1“ jedoch zuerst deklariert. Sie wird also zuerst ausgewertet und die App wird für eine URL geöffnet, die mit „/path1“ übereinstimmt. Die zweite Regel, die alle URLs vom Öffnen der App ausschließt, wird als Zweites ausgewertet, aber nur, wenn die erste Regel nicht zutrifft.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Wenn in der Liste der deklarierten Komponenten keine Übereinstimmungen gefunden werden, wird die App nicht über die URL geöffnet. Im folgenden Beispiel stimmt keiner der Pfade mit „/path3“ überein. Das Gerät behandelt diesen Pfad daher als ausgeschlossen.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Dieses Verhalten ist wichtig, wenn Sie mit dynamic_app_link_components nur bestimmte URL-Teile ausschließen, aber alle anderen zulassen möchten. Wenn im folgenden Beispiel die letzte Regel zum Zulassen aller verbleibenden Pfade weggelassen wird, werden alle URLs aus der App ausgeschlossen.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Bereich der dynamischen Regeln richtig festlegen

Wenn Sie serverseitige Regeln für die Verwendung mit dynamischen App-Links in Android 15 und höher definieren, ist es wichtig, sie entsprechend zu beschränken, damit sie mit den statischen Intent-Filtern in Ihrem App-Manifest funktionieren und diese ergänzen.

In der Datei „assetlinks.json“ deklarierte dynamische Regeln können nur Regeln für die Hosts angeben, die Sie in der Datei AndroidManifest.xml Ihrer App deklarieren. Die dynamischen Regeln können den Umfang der URL-Regeln, die Sie statisch in Ihrem App-Manifest deklarieren, nicht erweitern.

Aus diesem Grund empfehlen wir, diesen Ansatz für Ihre dynamischen und statischen Regeln zu verwenden:

  • Legen Sie in Ihrem App-Manifest Regeln mit einem möglichst breiten Geltungsbereich fest, z. B. indem Sie nur das Schema und die Domain deklarieren.
  • Verlassen Sie sich auf die serverseitigen dynamischen Regeln für weitere Optimierungen, z. B. Routing auf Pfadebene.

Mit dieser idealen Konfiguration können Sie bei Bedarf dynamisch neue App-Link-Pfade in der Datei „assetlinks.json“ hinzufügen, da Sie wissen, dass sie in den breiten Bereich passen, den Sie im App-Manifest festgelegt haben.

Damit Ihre Regeln richtig verarbeitet werden, deklarieren Sie nur ein „dynamic_app_link_components“-Objekt in den Anweisungen für eine bestimmte Website, Beziehung und App.

  • Suchen Sie nach mehreren Anweisungen für dieselbe Website, Beziehung und App, die ein „dynamic_app_link_components“-Objekt deklarieren.
  • Suchen Sie nach mehreren dynamic_app_link_components-Objekten, die in einer einzelnen Anweisung deklariert sind.

In solchen Fällen kann Android nicht garantieren, welche Konfiguration für dynamische Regeln verwendet wird.

Kompatibilität dynamischer Regeln mit früheren App-Link-Konfigurationen

Wenn Sie App-Links bereits unterstützen, können Sie die Unterstützung für dynamische App-Links direkt in Ihrer vorhandenen assetlinks.json-Datei hinzufügen. Die Beziehungsfelder für die Bestätigung Ihrer App-Links bleiben unverändert. Sie können die neuen Erweiterungsfelder für dynamische Regeln ohne weitere Änderungen hinzufügen.

Android-Geräte mit Android 14 (API-Level 34 oder niedriger) ignorieren die neuen Felder für Beziehungserweiterungen für dynamische Regeln, während Geräte mit Android 15 und höher diese Regeln mit den im Manifest definierten Regeln zusammenführen.

JSON-Bestätigungsdatei veröffentlichen

Sie müssen Ihre JSON-Bestätigungsdatei am folgenden Speicherort veröffentlichen:

https://domain.name/.well-known/assetlinks.json

Achten Sie auf Folgendes:

  • Die assetlinks.json-Datei wird mit dem Inhaltstyp application/json bereitgestellt.
  • Auf die Datei assetlinks.json muss über eine HTTPS-Verbindung zugegriffen werden können, unabhängig davon, ob in den Intent-Filtern Ihrer App HTTPS als Datenschema deklariert ist.
  • Auf die assetlinks.json-Datei muss ohne Weiterleitungen zugegriffen werden können (keine 301- oder 302-Weiterleitungen).
  • Wenn deine App-Links mehrere Hostdomains unterstützen, musst du die Datei assetlinks.json auf jeder Domain veröffentlichen. Weitere Informationen finden Sie unter App-Verknüpfung für mehrere Hosts unterstützen.
  • Veröffentlichen Sie Ihre App nicht mit Test-URLs in der Manifestdatei, die möglicherweise nicht öffentlich zugänglich sind (z. B. URLs, die nur über ein VPN zugänglich sind). In solchen Fällen können Sie Build-Varianten konfigurieren, um eine andere Manifestdatei für Entwicklungs-Builds zu generieren.

Weitere Informationen finden Sie in den folgenden Leitfäden: