Intent-Filter für App-Links hinzufügen

App-Links sind Deeplinks, die das HTTP- oder HTTPS-Schema verwenden und von Android als mit Ihrer Website verknüpft bestätigt werden. So registrieren Sie Ihre App für die Verarbeitung von App-Links:

1. Fügen Sie dem App-Manifest einen oder mehrere Intent-Filter hinzu, in denen die Domain oder URLs Ihrer Website angegeben werden.
2. Fügen Sie autoVerify="true"attribute den Intent-Filterelementen hinzu. Dadurch wird dem System signalisiert, dass es versuchen soll, das Schema und die Hostdomains mit der assetlinks.json-Konfiguration Ihrer Website abzugleichen.
3. Websiteverknüpfungen deklarieren

Das Folgende ist ein Beispiel für eine App-Link-Deklaration mit Schemas und Hosts sowie autoVerify="true:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <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" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

Wichtige Punkte zum Code

• AutoVerify: Das Attribut android:autoVerify="true" ist für App-Links erforderlich. Es signalisiert dem System, dass es versuchen soll, die Verknüpfung zwischen Ihrer App und den in den <data>-Tags angegebenen Schemas und Domains zu bestätigen. Es wird empfohlen, jedem Intent-Filter, der überprüft werden soll, autoVerify="true hinzuzufügen.
• Datenelemente: Jeder App-Link-Intent-Filter muss ein oder mehrere <data>-Elemente enthalten, in denen die Schemas und Hostformate angegeben sind, die mit Ihrer überprüfbaren Websitedomain übereinstimmen.
• Schemes: Der Intent-Filter muss <data>-Elemente für die Schemas http und https enthalten.

• Hosts: Optional können Sie <data>-Elemente hinzufügen, die mit einem oder mehreren Hosts übereinstimmen. Verwenden Sie einen Platzhalter (*), um mehrere Subdomains (z. B. *.example.com) abzugleichen. Das System versucht, jeden Host anhand der Datei „assetlinks.json“ auf Ihrer Website zu bestätigen. Das Routing auf Pfadebene sollte über die Datei „assetlinks.json“ erfolgen (siehe den Abschnitt zu Best Practices unten).

• Mehrere Hosts: Wenn Sie mehrere Hostdomains deklarieren, versucht das System (unter Android 12 und höher), jede einzelne zu bestätigen. Wenn ein Host bestätigt wird, wird die App zum Standard-Handler für Links von diesem bestätigten Host. Bei Android 11 und niedriger schlägt die Überprüfung fehl, wenn auch nur ein Host nicht überprüft werden kann.

• Mehrere Intent-Filter: Wenn Sie eindeutige URLs (z. B. eine bestimmte Kombination aus Schema und Host) deklarieren möchten, ist es wichtig, separate Filter zu erstellen. Mehrere <data>-Elemente im selben Intent-Filter werden zusammengeführt, um alle Variationen ihrer kombinierten Attribute zu berücksichtigen.

Hinweise zu Manifestfilterregeln

Wenn Sie Filter für die Verwendung mit dynamischen App-Links in Android 15 und höher einrichten, ist es wichtig, dass die dynamischen Regeln, die in der serverseitigen Datei „assetlinks.json“ deklariert werden, den Umfang der URL-Regeln, die Sie statisch in Ihrem App-Manifest deklarieren, nicht erweitern können.

Aus diesem Grund empfehlen wir diesen Ansatz:

• Legen Sie im App-Manifest den größtmöglichen Umfang fest, z. B. indem Sie nur das Schema und die Domain deklarieren.
• Verlassen Sie sich auf die serverseitigen assetlinks.json-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.

App-Links für mehrere Hosts unterstützen

Das System muss den in den Datenelementen der URL-Intent-Filter der App angegebenen Host anhand der Digital Asset Links-Dateien überprüfen können, die in den jeweiligen Webdomains in diesem Intent-Filter gehostet werden. Wenn die Überprüfung fehlschlägt, greift das System auf das Standardverhalten zurück, um die Intention aufzulösen, wie unter Deeplinks zu App-Inhalten erstellen beschrieben. Die App kann jedoch weiterhin als Standard-Handler für alle URL-Muster überprüft werden, die in den anderen Intent-Filtern der App definiert sind.

Eine App mit den folgenden Intent-Filtern würde die Überprüfung beispielsweise nur für https://www.example.com bestehen, wenn eine assetlinks.json-Datei unter https://www.example.com/.well-known/assetlinks.json, aber nicht unter https://www.example.net/.well-known/assetlinks.json gefunden würde:

<application>

  <activity android:name="MainActivity">
    <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="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <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" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

App-Verknüpfung für mehrere Subdomains unterstützen

Im Digital Asset Links-Protokoll werden Subdomains in Ihren Intent-Filtern als eindeutige, separate Hosts behandelt. Wenn in Ihrem Intent-Filter also mehrere Hosts mit unterschiedlichen Subdomains aufgeführt sind, müssen Sie auf jeder Domain eine gültige assetlinks.json veröffentlichen. Der folgende Intent-Filter enthält beispielsweise www.example.com und mobile.example.com als akzeptierte Intent-URL-Hosts. Eine gültige assetlinks.json muss also sowohl unter https://www.example.com/.well-known/assetlinks.json als auch unter https://mobile.example.com/.well-known/assetlinks.json veröffentlicht werden.

<application>
  <activity android:name="MainActivity">
    <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" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

Wenn Sie Ihren Hostnamen mit einem Platzhalter deklarieren (z. B. *.example.com), müssen Sie die Datei assetlinks.json im Stamm-Hostname (example.com) veröffentlichen. Eine App mit dem folgenden Intent-Filter besteht beispielsweise die Bestätigung für jeden untergeordneten Namen von example.com (z. B. foo.example.com), sofern die Datei assetlinks.json unter https://example.com/.well-known/assetlinks.json veröffentlicht wird:

<application>
  <activity android:name="MainActivity">
    <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" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Prüfen, ob mehrere Apps mit derselben Domain verknüpft sind

Wenn Sie mehrere Apps veröffentlichen, die jeweils mit derselben Domain verknüpft sind, können sie alle erfolgreich bestätigt werden. Wenn die Apps jedoch denselben Domainhost und ‑pfad auflösen können, wie es bei Lite- und Vollversionen einer App der Fall sein kann, kann nur die zuletzt installierte App Web-Intents für diese Domain auflösen.

Prüfen Sie in einem solchen Fall, ob auf dem Gerät des Nutzers möglicherweise inkompatible Apps installiert sind, sofern Sie die erforderliche Paketsichtbarkeit haben. Zeigen Sie dann in Ihrer App ein benutzerdefiniertes Auswahlfeld mit den Ergebnissen des Aufrufs von queryIntentActivities an. Der Nutzer kann seine bevorzugte App aus der Liste der übereinstimmenden Apps auswählen, die im Dialogfeld angezeigt wird.

Abwärtskompatibilität von dynamischen App-Links für Android 14 und niedriger

Funktionen für dynamische App-Links, einschließlich erweiterter Abgleichsregeln in assetlinks.json und der Verwendung von <uri-relative-filter-group>, werden nur unter Android 15 (API‑Level 35) und höher vollständig unterstützt.

Unter Android 14 (API‑Level 34) und niedriger berücksichtigt das System bei der App-Link-Bestätigung nur die scheme- und host-Elemente, die in den <data>-Elementen Ihres Manifests deklariert sind. Pfadspezifische Regeln, Ausschlüsse und dynamische Aktualisierungen aus assetlinks.json werden nicht angewendet.

Wenn in Ihrem Manifest also nur scheme und host angegeben sind, erfasst Ihre App unter Android 14 und niedriger möglicherweise unerwartet alle Pfade für die bestätigte Domain, unabhängig von den pfadspezifischen Regeln, die in Ihrem assetlinks.json für Android 15 und höher definiert sind.

Fallback-Strategie für niedrigere Android-Versionen, die ohne Deeplinks konfiguriert werden

Wenn Sie verhindern möchten, dass Ihre App unter Android 14 und niedriger alle Links für eine Domain verarbeitet, obwohl Sie dynamische App-Links für spezifischere Pfade unter Android 15 und höher verwenden möchten, fügen Sie dem Intent-Filter in Ihrem Manifest einen nicht übereinstimmenden Pfad hinzu. Fügen Sie ein <data>-Element mit einem android:path-Attribut hinzu, das wahrscheinlich nie ein gültiger Pfad für Ihre Links sein wird. Dadurch wird sichergestellt, dass der Intent-Filter auf niedrigeren Versionen nicht mit allen Pfaden übereinstimmt.

Beispiel:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <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="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

Wenn Sie <data android:path="/no_match_for_older_android_versions" /> hinzufügen, wird dafür gesorgt, dass dieser Intent-Filter unter Android 14 und niedriger nicht mit eingehenden Links übereinstimmt. Gleichzeitig kann die Domain aber weiterhin für die Verwendung mit Dynamic App Links unter Android 15 und höher anhand der erweiterten Abgleichsregeln in Ihren assetlinks.json-Regeln bestätigt werden.

Migration vorhandener App-Links

Wenn Sie bereits App-Links mit spezifischen Pfadregeln (z. B. android:pathPrefix) in Ihrem Manifest haben und dynamische App-Links unter Android 15 und höher verwenden möchten, können Sie das Element <uri-relative-filter-group> direkt zu Ihren vorhandenen Intent-Filtern hinzufügen.

Da das <uri-relative-filter-group>-Element in Android 14 und niedriger ignoriert wird, funktionieren Ihre vorhandenen App-Links auf Geräten mit niedrigeren Android-Versionen weiterhin wie bisher.

Sie müssen jedoch sorgfältig abwägen, wie Android 15 und höher die „gemischte“ Konfiguration bewertet:

• Filterung in zwei Ebenen:Unter Android 15 und höher wertet das System Intent-Filter als Vereinigung aus. Eine URL besteht die Manifestprüfung, wenn sie entweder Ihre alten statischen <data>-Tags oder die allgemeinen Regeln in Ihrem <uri-relative-filter-group> erfüllt. Wenn die URL diesen ersten Manifestcheck besteht, wendet das System die dynamischen Regeln an, die in Ihrer assetlinks.json-Datei als zweite Ebene der detaillierten Filterung definiert sind. Das bedeutet, dass die serverseitigen JSON-Regeln letztendlich festlegen, für welche der übereinstimmenden URLs die App tatsächlich geöffnet wird.

Beispiel für eine Hybridkonfiguration:

<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" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>