Deeplink für ein Ziel erstellen

Unter Android ist ein Deeplink ein Link, über den Sie direkt zu einem bestimmten Ziel innerhalb einer App weitergeleitet werden.

Mit der Navigationskomponente können Sie zwei verschiedene Arten von Deeplinks erstellen: explizite und implizite.

Expliziten Deeplink erstellen

Ein expliziter Deeplink ist eine einzelne Instanz eines Deeplinks, über den Nutzer mithilfe eines PendingIntent zu einer bestimmten Stelle in Ihrer App weitergeleitet werden. Sie können einen expliziten Deeplink beispielsweise in einer Benachrichtigung oder einem App-Widget anzeigen lassen.

Wenn ein Nutzer Ihre App über einen expliziten Deeplink öffnet, wird der Task-Backstack gelöscht und durch das Deeplink-Ziel ersetzt. Wenn Sie Diagramme verschachteln, wird dem Stack auch das Startziel jeder Verschachtelungsebene hinzugefügt, also das Startziel jedes <navigation>-Elements in der Hierarchie. Wenn ein Nutzer also über einen Deeplink zu einer Zielseite gelangt und die Schaltfläche „Zurück“ drückt, wird er durch den Navigationsstack zurückgeführt, als wäre er über den Einstiegspunkt in Ihre App gelangt.

Mit der Klasse NavDeepLinkBuilder können Sie ein PendingIntent erstellen, wie im folgenden Beispiel gezeigt. Wenn der angegebene Kontext kein Activity ist, verwendet der Konstruktor PackageManager.getLaunchIntentForPackage() als Standardaktivität, sofern verfügbar.

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

Standardmäßig startet NavDeepLinkBuilder Ihren expliziten Deeplink im Standardstart Activity, der im Manifest Ihrer App deklariert ist. Wenn sich Ihr NavHost in einer anderen Aktivität befindet, müssen Sie beim Erstellen des Deeplink-Builders den zugehörigen Komponentennamen angeben:

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

Wenn Sie eine ComponentName haben, können Sie sie direkt an den Builder übergeben:

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

Wenn Sie bereits ein NavController-Element haben, können Sie auch mit NavController.createDeepLink() einen Deeplink erstellen.

Hinweis: Wenn für einen Bildschirm eine Aktion wie die Anmeldung erforderlich ist, bevor der Nutzer darauf zugreifen kann, folgen Sie der Anleitung unter Bedingte Navigation, um den Nutzer bedingt über einen Deeplink weiterzuleiten, wenn er diesen Bildschirm erreicht.

Impliziten Deeplink erstellen

Ein impliziter Deeplink bezieht sich auf ein bestimmtes Ziel in einer App. Wenn der Deeplink aufgerufen wird, z. B. wenn ein Nutzer auf einen Link klickt, kann Android Ihre App mit dem entsprechenden Ziel öffnen.

Deeplinks können anhand von URI, Intent-Aktionen und MIME-Typen abgeglichen werden. Sie können mehrere Keyword-Optionen für einen einzelnen Deeplink angeben. Beachten Sie jedoch, dass die Übereinstimmung des URI-Arguments zuerst priorisiert wird, gefolgt von der Aktion und dann dem MIME-Typ.

Hier ein Beispiel für einen Deeplink, der einen URI, eine Aktion und einen MIME-Typ enthält:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

Sie können auch den Navigationseditor verwenden, um einen impliziten Deeplink zu einem Ziel zu erstellen. Gehen Sie dazu so vor:

1. Wählen Sie auf dem Tab Design des Navigationseditors das Ziel für den Deeplink aus.
2. Klicken Sie im Bereich Attribute unter Deeplinks auf +.

3. Geben Sie im Dialogfeld Deeplink hinzufügen die Informationen für Ihren Deeplink ein.

   Beachten Sie Folgendes:

   • Für URIs ohne Schema wird entweder HTTP oder HTTPS angenommen. Beispielsweise entspricht www.google.com sowohl http://www.google.com als auch https://www.google.com.
   • Platzhalter für Pfadparameter im Format {placeholder_name} stimmen mit einem oder mehreren Zeichen überein. Beispielsweise führt http://www.example.com/users/{id} zu Übereinstimmungen mit http://www.example.com/users/4. Die Navigationskomponente versucht, die Platzhalterwerte in die entsprechenden Typen zu parsen, indem Platzhalternamen mit den definierten Argumenten abgeglichen werden, die für das Deeplink-Ziel definiert sind. Wenn kein Argument mit demselben Namen definiert ist, wird für den Argumentwert ein Standardtyp String verwendet. Mit dem Platzhalter .* können Sie 0 oder mehr Zeichen abgleichen.
   • Platzhalter für Abfrageparameter können anstelle oder in Verbindung mit Pfadparametern verwendet werden. Beispiel: http://www.example.com/users/{id}?myarg={myarg} stimmt mit http://www.example.com/users/4?myarg=28 überein.
   • Abfrageparameter-Platzhalter für Variablen, die mit Standard- oder optionalen Werten definiert sind, müssen nicht übereinstimmen. Zum Beispiel stimmt http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} mit http://www.example.com/users/4?arg2=28 oder http://www.example.com/users/4?arg1=7 überein. Das ist bei Pfadparametern nicht der Fall. http://www.example.com/users?arg1=7&arg2=28 entspricht beispielsweise nicht dem obigen Muster, da der erforderliche Pfadparameter nicht angegeben ist.
   • Fremde Abfrageparameter wirken sich nicht auf die Deeplink-URI-Übereinstimmung aus. Beispiel: http://www.example.com/users/{id} stimmt mit http://www.example.com/users/4?extraneousParam=7 überein, auch wenn extraneousParam im URI-Muster nicht definiert ist.

4. Optional: Klicken Sie das Kästchen Automatisch bestätigen an, damit Google überprüft, ob Sie der Inhaber des URIs sind. Weitere Informationen finden Sie unter Android-App-Links überprüfen.

5. Klicken Sie auf Hinzufügen. Über dem ausgewählten Ziel wird ein Linksymbol  angezeigt, um anzugeben, dass es sich um ein Deeplink-Ziel handelt.

6. Klicken Sie auf den Tab Code, um zur XML-Ansicht zu wechseln. Dem Ziel wurde ein verschachteltes <deepLink>-Element hinzugefügt:

   <deepLink app:uri="https://www.google.com" />
   

Zum Aktivieren von impliziten Deeplinks müssen Sie außerdem die Datei manifest.xml Ihrer App ergänzen. Fügen Sie einer Aktivität ein einzelnes <nav-graph>-Element hinzu, das auf ein vorhandenes Navigationsdiagramm verweist, wie im folgenden Beispiel gezeigt:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

Beim Erstellen des Projekts ersetzt die Navigationskomponente das <nav-graph>-Element durch generierte <intent-filter>-Elemente, damit sie mit allen Deeplinks im Navigationsdiagramm übereinstimmen.

Wenn ein impliziter Deeplink ausgelöst wird, hängt der Status des Backstacks davon ab, ob der implizite Intent mit dem Flag Intent.FLAG_ACTIVITY_NEW_TASK gestartet wurde:

• Wenn das Flag gesetzt ist, wird der Back-Stack der Aufgabe gelöscht und durch das Ziel des Deeplinks ersetzt. Wie bei expliziten Deeplinks wird auch beim Verschachteln von Grafiken das Startziel jeder Verschachtelungsebene – also das Startziel jedes <navigation>-Elements in der Hierarchie – dem Stack hinzugefügt. Wenn ein Nutzer also über einen Deeplink auf die Schaltfläche „Zurück“ klickt, wird er durch den Navigationsstack zurückgeführt, als wäre er über den Einstiegspunkt in Ihre App gelangt.
• Wenn das Flag nicht festgelegt ist, bleiben Sie im Task-Stack der vorherigen App, in der der implizite Deeplink ausgelöst wurde. In diesem Fall kehren Sie mit der Schaltfläche „Zurück“ zur vorherigen App zurück. Mit der Schaltfläche „Oben“ wird die Aufgabe Ihrer App im übergeordneten Zielknoten des Navigationsgraphen gestartet.

Umgang mit Deeplinks

Es wird dringend empfohlen, bei der Navigation immer die Standardeinstellung launchMode von standard zu verwenden. Wenn Sie den Startmodus standard verwenden, werden Deeplinks automatisch von der Navigation verarbeitet. Dazu wird handleDeepLink() aufgerufen, um alle expliziten oder impliziten Deeplinks in der Intent zu verarbeiten. Das geschieht jedoch nicht automatisch, wenn die Activity wiederverwendet wird, wenn eine alternative launchMode wie singleTop verwendet wird. In diesem Fall müssen Sie handleDeepLink() manuell in onNewIntent() aufrufen, wie im folgenden Beispiel gezeigt:

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

Weitere Informationen

Weitere Informationen zur Navigation finden Sie in den folgenden Ressourcen.

Produktproben

• Grundlegendes Beispiel für die Navigation in Android-Architekturkomponenten

Codelabs

• Codelab zur Navigation

Videos

• Android Jetpack: UI-Navigation mit Navigation Controller verwalten (Google I/O '18)