Websitezuordnungen und dynamische Regeln konfigurieren

Zur Unterstützung von App-Links 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 bestätigen.

Bei dynamischen App-Links in Android 15 und höher definieren Sie in der Datei assetlinks.json auch die Konfiguration Ihrer dynamischen Regeln, 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 dieser Anleitung wird beschrieben, wie Sie eine assetlinks.json-Datei vorbereiten und auf Ihrer Website veröffentlichen. Alternativ können Sie eine assetlinks.json-Datei mit dem Play Deep Links-Tool 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-Fingerabdrücke des Signaturzertifikats Ihrer App. Mit dem folgenden Befehl können Sie den Fingerabdruck mit dem Java-Tool „keytool“ generieren:

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

Dieses Feld unterstützt mehrere Fingerabdrücke, mit denen verschiedene Versionen Ihrer App unterstützt werden können, z. B. Debug- und Produktionsversionen. Wenn Sie die Play App-Signatur für Ihre App verwenden, stimmt der Zertifikats fingerabdruck, der durch Ausführen von keytool lokal erstellt wird, in der Regel nicht mit dem auf den Geräten der Nutzer überein. Sie können in Ihrem Play Console-Entwicklerkonto unter Release > Setup > App signing prüfen, ob Sie die Play App-Signatur für Ihre App verwenden. Wenn dies der Fall ist, finden Sie auf derselben Seite auch das richtige Digital Asset Links-JSON-Snippet für Ihre App.

Die folgende assetlinks.json-Beispieldatei gewährt einer com.example-Android-App die Berechtigung zum Öffnen von Links:

[{
  "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 Anweisungsdatei, in der die Verknüpfung mit zwei Apps separat deklariert wird. Sie befindet sich unter https://www.example.com/.well-known/assetlinks.json:

[{
  "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. App 1 kann beispielsweise einen Intent-Filter für https://example.com/articles deklarieren und App 2 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 Verknüpfung von „example.com“ und „example.net“ mit „app1“ deklarieren. Die erste Liste 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 Liste 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 Regeln für den Abgleich von Deeplinks verwenden, die mit den Regeln zusammenarbeiten, die Sie statisch im Manifest Ihrer App 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 dynamische Konfiguration mit der statischen Konfiguration im Manifest der App zusammen. Im Folgenden sehen 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-Relation-Erweiterung namens dynamic_app_link_components hinzugefügt, in der Sie Ihre dynamischen Regeln konfigurieren.
Dynamische Regeln können Musterabgleiche 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 Musterabgleiche für Pfad ("/"), Fragment ("#"), Suchparameter ("?") und ausgeschlossene Musterabgleiche ("exclude").
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.

In dynamischen Regeln können nur Regeln angegeben werden, die im Rahmen der Domains gelten, die Sie in der Manifestdatei Ihrer App deklarieren. Siehe unten.

Dynamische Regeln deklarieren

Dynamische App-Links unterstützen eine neue Relation-Erweiterung dynamic_app_link_components, die ein Array von Regelobjekten enthält. Jede Regel wird mit Musterabgleichen für Pfade, Fragmente und Suchparameter definiert, die Ihre App öffnen. Musterabgleiche können auch einzeln ausgeschlossen werden, damit sie Ihre App nicht öffnen. Alle diese 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
Abfrageparameterabgleich
- Schlüssel: "?"
- Wert: Dictionary zum Abgleichen von Schlüssel/Wert-Paaren in den URL-Suchparametern.
- Das Dictionary "?", {"dl": "*", "in_app":"true" stimmt beispielsweise 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 müssen nicht alle Schlüssel/Wert-Paare im Abfragestring mit dem Dictionary übereinstimmen, aber für jeden Dictionary-Eintrag muss eine Übereinstimmung gefunden werden.
- Das Dictionary 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 boolescher Wert für jede in dynamic_app_link_components definierte Regel (siehe Beispiel).

In Musterabgleichen können Sie diese Sonderzeichen verwenden:

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

Für Werte gelten keine weiteren Zeichenbeschränkungen.

Dynamische Regeln anordnen

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 ausgeschlossen werden, damit die App nicht geöffnet wird. 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 öffnet die App für eine URL, die mit „/path1“ übereinstimmt. Die zweite Regel, die alle URLs ausschließt, damit die App nicht geöffnet wird, wird als Zweites ausgewertet, aber nur, wenn die erste Regel keine Übereinstimmung ergibt.

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, daher behandelt das Gerät diesen Pfad 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 Sie im folgenden Beispiel die letzte Regel weglassen, um alle verbleibenden Pfade zuzulassen, werden alle URLs von der App ausgeschlossen.

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 einzugrenzen, damit sie mit den statischen Intent-Filtern funktionieren und diese ergänzen, die im App-Manifest Ihrer App deklariert sind.

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 im App-Manifest Ihrer App deklarieren, nicht erweitern.

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

Legen Sie im 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 großen Umfang passen, den Sie im App-Manifest festgelegt haben.

`dynamic_app_link_components` nur einmal deklarieren

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 Datei „assetlinks.json“ hinzufügen. Die Beziehungsfelder zum Bestätigen Ihrer App-Links bleiben gleich und Sie können die neuen Felder für die Beziehungserweiterung 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 die Beziehungserweiterung 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 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 Datei assetlinks.json muss ohne Weiterleitungen zugegriffen werden können (keine 301- oder 302-Weiterleitungen).
Wenn Ihre App-Links mehrere Hostdomains unterstützen, müssen Sie die Datei assetlinks.json auf jeder Domain veröffentlichen. Weitere Informationen finden Sie unter App-Links für mehrere Hosts unterstützen.
Veröffentlichen Sie Ihre App nicht mit Test-URLs in der Manifestdatei, auf die die Öffentlichkeit möglicherweise nicht zugreifen kann (z. B. URLs, auf die nur mit einem 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 verwandten Anleitungen: