Deeplinks erstellen

Über Deeplinks können Nutzer direkt aus Webbrowsern, Benachrichtigungen, sozialen Medien, Anzeigen und anderen Quellen in Ihre App gelangen. Deeplinks ermöglichen direkte Übergänge von App zu App und von Web zu App, mit denen Sie die Interaktion durch kontextbezogene, zielgerichtete Inhalte steigern können.

In diesem Leitfaden wird erläutert, wie Deeplinks funktionieren und wie du Deeplinks zu deinen Inhalten erstellst und testest.

Für Deeplinks, die auf Ihre eigene Website oder Domains verweisen, empfehlen wir die Verwendung von App-Links, da diese eine nahtlose, vertrauenswürdige Nutzererfahrung bieten.

So funktionieren Deeplinks

Deep-Links sind eine allgemeine Systemfunktion von Android, die in allen Versionen und auf allen Geräten unterstützt wird. Dabei wird das Intent-System von Android genutzt, um Deeplinks an die entsprechenden Apps weiterzuleiten. Apps, die einen bestimmten Deeplink-URI verarbeiten sollen, deklarieren einen entsprechenden Intent-Filter in ihren App-Manifestdateien.

Wenn der Nutzer zur Laufzeit auf einen Link tippt, löst Android einen Intent aus und versucht, ihn an eine App weiterzuleiten. Da mehrere Apps Intent-Filter deklarieren können, die mit einem bestimmten URI übereinstimmen, führt Android die folgenden Aktionen in dieser Reihenfolge aus, um den Intent weiterzuleiten:

1. Öffnen Sie die Standard-App des Nutzers, die den URI verarbeiten kann, falls eine festgelegt wurde.
2. Öffnen Sie die einzige verfügbare App, die den URI verarbeiten kann.
3. Dem Nutzer erlauben, eine App aus einem Dialogfeld zur Mehrdeutigkeitsauflösung auszuwählen.

Das bedeutet, dass es trotz Übereinstimmung der Intent-Filter mit einem bestimmten URI keine Garantie dafür gibt, dass das System den Deeplink-Intent an deine App weiterleitet. Der Nutzer spielt eine wichtige Rolle bei der Verwaltung der App, die den Intent verarbeitet. Das gibt ihm Kontrolle und Auswahlmöglichkeiten. Wenn Sie mehr Kontrolle über Deeplinks zu Ihrer eigenen Website und Ihren Domains haben möchten, können Sie App-Links verwenden.

Im Dialogfeld zur Mehrdeutigkeitsauflösung von Android werden dem Nutzer alle installierten Apps angezeigt, die für die Verarbeitung eines Deeplink-Intents registriert sind. Der Nutzer kann auch eine App als Standard für diesen Linktyp auswählen. Sobald der Nutzer eine Standardeinstellung festgelegt hat, wird das Dialogfeld für diesen Intent nicht mehr angezeigt und die ausgewählte App wird automatisch geöffnet.

Abbildung 1. Dialogfeld zur Mehrdeutigkeitsauflösung

Das Verhalten des Dialogfelds zur Mehrdeutigkeitsauflösung hat sich im Laufe der Android-Versionen weiterentwickelt. Unter Android 12 und höher werden Weblinks, die keine bestätigten App-Links sind, standardmäßig in einem Webbrowser geöffnet. In früheren Versionen wurde möglicherweise ein Auswahldialog angezeigt, wenn eine App den Weblink verarbeiten konnte.

Hinweis: Ab Android 12 (API-Level 31) wird ein allgemeiner Web-Intent nur dann zu einer Aktivität in Ihrer App aufgelöst, wenn Ihre App für die spezifische Domain genehmigt wurde, die in diesem Web-Intent enthalten ist. Wenn Ihre App nicht für die Domain genehmigt wurde, wird der Web-Intent stattdessen in der Standardbrowser-App des Nutzers aufgelöst.

Arten von Deeplinks

Es gibt drei Arten von Deeplinks, die Sie unter Android unterstützen können:

• Benutzerdefinierte Deeplinks: Diese Deeplinks verwenden ein benutzerdefiniertes URI-Schema (z. B. example://products/123), um Nutzer direkt zu bestimmten Inhalten in einer App weiterzuleiten. Sie sind nützlich für die interne Navigation oder Links von Quellen, die Sie kontrollieren. Es handelt sich jedoch nicht um Standard-Weblinks und sie können weiterhin das Dialogfeld zur Mehrdeutigkeitsauflösung auslösen, wenn eine andere App dasselbe benutzerdefinierte Schema registriert.
• Weblinks: Das sind Deeplinks, die die Standardschemas http und https verwenden. Sie sind vielseitiger, da es sich um Standard-URLs handelt. Unter Android 12 und höher wird jedoch fast immer der Dialog zur Mehrdeutigkeitsauflösung ausgelöst. Das bedeutet, dass sie wahrscheinlich standardmäßig vom Webbrowser des Nutzers verarbeitet werden, anstatt an Ihre App weitergeleitet zu werden.
• App-Links: Diese sind seit Android 6.0 (API-Level 23) verfügbar und sind bestätigte Weblinks. Durch die Verknüpfung einer Website können Sie dem Android-System nachweisen, dass Sie der Inhaber der Domain sind. Nach der Bestätigung leitet das System Links für diese Domain automatisch direkt an Ihre App weiter und überspringt den Mehrdeutigkeitsauflösungsdialog vollständig. So entsteht eine vertrauenswürdige und nahtlose Umgebung für Ihre Nutzer.

Intent-Filter für eingehende Links hinzufügen

Wenn Sie einen Link zu Ihren App-Inhalten erstellen möchten, fügen Sie Ihrem Manifest einen Intent-Filter hinzu, der die folgenden Elemente und Attributwerte enthält:

<action>

Geben Sie die Intent-Aktion ACTION_VIEW an, damit der Intent-Filter über die Google Suche erreicht werden kann.

<data>

Fügen Sie ein oder mehrere <data>-Tags hinzu, die jeweils ein URI-Format darstellen, das zur Aktivität führt. Das <data>-Tag muss mindestens das Attribut android:scheme enthalten.

Sie können weitere Attribute hinzufügen, um den von der Aktivität akzeptierten URI-Typ weiter einzugrenzen. Beispielsweise können Sie mehrere Aktivitäten haben, die ähnliche URIs akzeptieren, sich aber je nach Pfad unterscheiden. Verwende in diesem Fall das Attribut android:path oder die Varianten pathPattern oder pathPrefix, um zu unterscheiden, welche Aktivität das System für verschiedene URI-Pfade öffnen soll.

<category>

Geben Sie die Kategorie BROWSABLE an. Er ist erforderlich, damit der Intent-Filter über einen Webbrowser zugänglich ist. Ohne sie kann ein Klick auf einen Link in einem Browser nicht zu Ihrer App führen.

Geben Sie auch die Kategorie DEFAULT an. Dadurch kann Ihre App auf implizite Intents reagieren. Andernfalls kann die Aktivität nur gestartet werden, wenn der Intent den Namen der App-Komponente angibt.

Das folgende XML-Snippet zeigt, wie Sie einen Intent-Filter in Ihrem Manifest für Deeplinks angeben können. Die URIs "example://gizmos" und "http://www.example.com/gizmos" werden beide in diese Aktivität aufgelöst.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos" -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos" -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

Die beiden Intent-Filter unterscheiden sich nur durch das <data>-Element. Es ist zwar möglich, mehrere <data>-Elemente in denselben Filter aufzunehmen, aber es ist wichtig, dass du separate Filter erstellst, wenn du eindeutige URLs deklarieren möchtest (z. B. eine bestimmte Kombination aus scheme und host). Mehrere <data>-Elemente im selben Intent-Filter werden nämlich zusammengeführt, um alle Varianten ihrer kombinierten Attribute zu berücksichtigen. Sie könnten beispielsweise Folgendes versuchen:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

Es mag den Anschein haben, dass nur https://www.example.com und app://open.my.app unterstützt werden. Tatsächlich werden jedoch diese beiden und die folgenden unterstützt: app://www.example.com und https://open.my.app.

Achtung: Wenn mehrere Aktivitäten Intent-Filter enthalten, die auf denselben verifizierten Android App Link verweisen, kann nicht garantiert werden, welche Aktivität den Link verarbeitet.

Nachdem Sie Ihrem App-Manifest Intent-Filter mit URIs für Aktivitätsinhalte hinzugefügt haben, kann Android alle Intent mit übereinstimmenden URIs zur Laufzeit an Ihre App weiterleiten.

Weitere Informationen zum Definieren von Intent-Filtern finden Sie unter Anderen Apps das Starten einer Aktivität erlauben.

Daten aus eingehenden Intents lesen

Sobald das System Ihre Aktivität über einen Intent-Filter startet, können Sie anhand der von Intent bereitgestellten Daten bestimmen, was gerendert werden soll. Rufen Sie die Methoden getData() und getAction() auf, um die Daten und die Aktion abzurufen, die mit der eingehenden Intent verknüpft sind. Sie können diese Methoden jederzeit während des Lebenszyklus der Aktivität aufrufen, sollten dies jedoch im Allgemeinen während früher Callbacks wie onCreate() oder onStart tun.

Hier ist ein Snippet, das zeigt, wie Daten aus einem Intent abgerufen werden:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

Befolgen Sie diese Best Practices, um die Nutzerfreundlichkeit zu verbessern:

• Über den Deeplink sollten Nutzer direkt zu den Inhalten gelangen, ohne dass Aufforderungen, Interstitial-Seiten oder Anmeldungen angezeigt werden. Achten Sie darauf, dass Nutzer die App-Inhalte auch dann sehen können, wenn sie die App noch nie geöffnet haben. Es ist in Ordnung, Nutzer bei nachfolgenden Interaktionen oder beim Öffnen der App über den Launcher aufzufordern.
• Folgen Sie der Designanleitung unter Navigation mit „Zurück“ und „Nach oben“, damit Ihre App die Erwartungen der Nutzer an die Rückwärtsnavigation erfüllt, nachdem sie über einen Deeplink in Ihre App gelangt sind.

Tiefenlinks testen

Mit der Android Debug Bridge und dem Activity Manager-Tool (am) kannst du testen, ob die Intent-Filter-URIs, die du für Deeplinks angegeben hast, zur richtigen App-Aktivität führen. Sie können den adb-Befehl für ein Gerät oder einen Emulator ausführen.

Die allgemeine Syntax zum Testen eines Intent-Filter-URIs mit adb lautet:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

Mit dem folgenden Befehl wird beispielsweise versucht, eine Ziel-App-Aktivität aufzurufen, die mit dem angegebenen URI verknüpft ist.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

Hinweis: Wenn Sie eine Sammlung primitiver Typen in einer Route definieren, z. B. @Serializable data class Product(val colors: List), lautet das automatisch generierte Deeplink-URL-Format basePath?colors={value}. Wenn Sie versuchen, einen URI mit mehreren Abfrageparametern anzugeben (z. B. basepath?colors=red&colors=blue), müssen Sie das kaufmännische Und-Zeichen maskieren (z. B. basepath?colors=red\&colors=blue).

Ab Android 17 können Sie das Flag --debug-link auch mit am start verwenden, um zu diagnostizieren, wie das System eine URL auflöst, und um übereinstimmende Intent-Filter oder Regeln für dynamische App-Links zu prüfen. Weitere Informationen finden Sie unter Linkauflösung mit dem Flag „debug-link“ diagnostizieren.

Die von dir festgelegte Manifestdeklaration und der Intent-Handler definieren die Verbindung zwischen deiner App und einer Website sowie die Verarbeitung eingehender Links. Damit das System Ihre App als Standard-Handler für eine Reihe von URIs behandelt, müssen Sie jedoch auch anfordern, dass das System diese Verbindung überprüft. Unter App-Links prüfen wird erläutert, wie Sie diese Prüfung implementieren.

Weitere Informationen zu Intents und App-Links finden Sie in den folgenden Ressourcen:

• Intents und Intent-Filter
• Anderen Apps das Starten einer Aktivität erlauben
• Android-App-Links mit Android Studio hinzufügen