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 Speicherort 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+ definieren Sie in der Datei assetlinks.json auch Ihre Konfiguration für dynamische Regeln, z. B. Mustervergleich für Pfad-, Fragment- und Abfrageparameter. Auf Android-Geräten mit Android 15 (API-Level 35) oder höher, auf denen Google-Dienste installiert sind, wird die Datei regelmäßig abgerufen und Ihre dynamische Konfiguration mit der statischen Konfiguration im App-Manifest zusammengeführt.

In dieser Anleitung wird beschrieben, wie Sie eine assetlinks.json-Datei vorbereiten und auf Ihrer Website veröffentlichen. Sie können die Datei assetlinks.json auch mit dem Play-Tool für Deeplinks oder dem App-Link-Assistenten in 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 build.gradle-Datei der App deklariert ist.
  • sha256_cert_fingerprints: Die SHA256-Fingerprints des Signaturzertifikats Ihrer App. Mit dem folgenden Befehl können Sie den Fingerabdruck mit dem Java-Schlüsseltool 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 Play App Signing für Ihre App verwenden, stimmt der Zertifikatsfingerabdruck, der durch lokales Ausführen von keytool erstellt 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 nachsehen, ob Sie die Play App-Signatur für Ihre App verwenden. Wenn dies der Fall ist, finden Sie auf derselben Seite auch den richtigen JSON-Snippet für Digital Asset Links für Ihre App.

Im folgenden Beispiel wird in der assetlinks.json-Datei einer com.example-Android-App das Recht 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 Dateiliste zeigt ein Beispiel für eine Erklärungsdatei, in der die Zuordnung zu zwei Apps separat deklariert wird und die 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. Beispiel: app1 deklariert einen Intent-Filter für https://example.com/articles und app2 deklariert einen Intent-Filter für https://example.com/videos.

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 Sie die Zuordnung von example.com und example.net zu app1 deklarieren. Im ersten Eintrag wird die Verknüpfung von example.com mit app1 gezeigt:

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

In der nächsten Liste sehen Sie die Zuordnung von example.net zu app1. Nur der Speicherort dieser Dateien 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 im App-Manifest definiert haben. In der Datei assetlinks.json definieren Sie dynamische Regeln. Dies 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 Ihre Konfiguration für dynamische 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 Erweiterung für Digital Asset Links-Beziehungen namens dynamic_app_link_components hinzugefügt, in der Sie Ihre dynamischen Regeln konfigurieren.
  • Dynamische Regeln können Musterabgleichsfunktionen für Pfad-, Fragment- und Abfrageparameter enthalten.
  • Sie können auch einen beliebigen Musterabgleich als ausgeschlossen markieren, damit übereinstimmende URLs Ihre App nicht öffnen.
  • In diesem Beispiel sehen Sie Beispiele für Tools zum Abgleich von Pfaden ("/"), Fragmenten ("#") und Abfrageparametern ("?") sowie ausgeschlossene Tools zum Abgleich ("exclude").
  • Wenn eines der Felder in der Datei fehlerhaft oder leer ist, werden die dynamischen Regeln von Android verworfen und das Gerät greift auf die Regeln zurück, die statisch im Manifest der App definiert sind.

In dynamischen Regeln können nur Regeln angegeben werden, die für die Domains gelten, die Sie im Manifest Ihrer App deklarieren. Siehe unten.

Dynamische Regeln deklarieren

Dynamic App Links unterstützt eine neue dynamic_app_link_components-Beziehungserweiterung, die ein Array von Regelobjekten enthält. Jede Regel wird mithilfe von Mustervergleichsfunktionen für Pfade, Fragmente und Abfrageparameter definiert, mit denen Ihre App geöffnet wird. Mustervergleichsfunktionen können auch einzeln ausgeschlossen werden, damit Ihre App nicht geöffnet wird. Alle diese Funktionen sind optional.

  • Pfadabgleich
    • Schlüssel: „/“
    • Wert: Einzelner String, passender Ausdruck für den URL-Pfad
  • Fragmentabgleich
    • Schlüssel: „#“
    • Wert: Einzelner String, passender Ausdruck für das URL-Fragment
  • Abfrageparameter-Übereinstimmung
    • Schlüssel: „?“
    • Wert: Dictionary zum Abgleichen von Schlüssel/Wert-Paaren in den URL-Suchparametern.
    • Beispiel: Das Dictionary {"?", {"dl": "*", "in_app":"true"} stimmt mit dem Suchanfragestring "?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 Suchstring „?lang=en&in_app=true&tz=pst&dl=abc“ übereinstimmen, nicht aber mit dem Suchstring „?lang=en&tz=pst&dl=abc“.
  • Ausgeschlossen
    • Schlüssel: „exclude“
    • Wert: Optionaler „true“-/„false“-Wert für jede in dynamic_app_link_components definierte Regel (siehe Beispiel).

Sie können diese Sonderzeichen in Mustervergleichsfunktionen verwenden:

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

Für Werte gelten keine weiteren Zeichenbeschränkungen.

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 entspricht allen Pfaden („*“), 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 verhindert, dass die App über URLs geöffnet wird, wird als Nächstes ausgewertet, aber nur, wenn die erste Regel keine Übereinstimmung ergibt.

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

Dynamische Regeln richtig eingrenzen

Wenn Sie Ihre serverseitigen Regeln für die Verwendung mit dynamischen App-Links in Android 15 und höher definieren, ist es wichtig, sie entsprechend zu begrenzen, damit sie mit den statischen Intent-Filtern, die in Ihrem App-Manifest deklariert sind, 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 AndroidManifest.xml-Datei Ihrer App deklarieren. Mit dynamischen Regeln kann der Umfang der URL-Regeln, die Sie statisch in Ihrem App-Manifest deklarieren, nicht erweitert werden.

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

  • Legen Sie in Ihrem App-Manifest Regeln mit dem größtmöglichen Umfang 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. das 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 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, in denen ein „dynamic_app_link_components“-Objekt deklariert wird.
  • 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 bereits App-Links unterstützen, können Sie die Unterstützung für dynamische App-Links direkt in Ihrer vorhandenen assetlinks.json-Datei hinzufügen. Die Beziehungsfelder zum Überprüfen Ihrer App-Links bleiben unverändert. Sie können die neuen Beziehungserweiterungsfelder für dynamische Regeln ohne weitere Änderungen hinzufügen.

Auf Android-Geräten mit Android 14 (API-Level 34 oder niedriger) werden die neuen Erweiterungsfelder für Beziehungen für dynamische Regeln ignoriert. Auf Geräten mit Android 15 und höher werden diese Regeln mit den in Ihrem Manifest definierten Regeln zusammengeführt.

JSON-Bestätigungsdatei veröffentlichen

Sie müssen Ihre JSON-Verifizierungsdatei am folgenden Ort veröffentlichen:

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

Achten Sie auf Folgendes:

  • Die Datei assetlinks.json 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 Ihre App-Links mehrere Hostdomains unterstützen, müssen Sie die assetlinks.json-Datei 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, auf die nur über ein VPN zugegriffen werden kann). In solchen Fällen können Sie Build-Varianten konfigurieren, um eine andere Manifestdatei für Entwickler-Builds zu generieren.

Weitere Informationen finden Sie in den folgenden Leitfäden: