Créer un lien profond pour une destination

Dans Android, un lien profond est un lien qui vous redirige directement vers une destination spécifique dans une application.

Le composant Navigation vous permet de créer deux types de liens profonds : les liens explicites et implicites.

Créer un lien profond explicite

Un lien profond explicite est une instance unique d'un lien profond qui utilise un PendingIntent pour rediriger les utilisateurs vers un emplacement spécifique de votre application. Vous pouvez afficher un lien profond explicite dans une notification ou un widget d'application, par exemple.

Lorsqu'un utilisateur ouvre votre application via un lien profond explicite, la pile "Retour" des tâches est effacée et remplacée par la destination du lien profond. Lorsque vous imbriquez des images, la destination de départ de chaque niveau d'imbrication (c'est-à-dire la destination de départ de chaque élément <navigation> de la hiérarchie) est également ajoutée à la pile. Cela signifie que lorsqu'un utilisateur appuie sur le bouton "Retour" à partir d'une destination de lien profond, il revient en arrière dans la pile de navigation comme s'il s'agissait d'une application ouverte depuis son point d'entrée.

Vous pouvez utiliser la classe NavDeepLinkBuilder pour construire un PendingIntent, comme illustré dans l'exemple ci-dessous. Notez que si le contexte fourni n'est pas un Activity, le constructeur utilise PackageManager.getLaunchIntentForPackage() comme activité par défaut à lancer, s'il est disponible.

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

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

Par défaut, NavDeepLinkBuilder lance votre lien profond explicite dans le lancement par défaut de Activity, qui est déclaré dans le fichier manifeste de votre application. Si votre NavHost se trouve dans une autre activité, vous devez indiquer son nom lorsque vous créez le générateur de liens profonds :

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

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

Si vous disposez d'un ComponentName, vous pouvez le transmettre directement au générateur :

val componentName = ...

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

ComponentName componentName = ...;

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

Si vous disposez déjà d'un NavController, vous pouvez également créer un lien profond à l'aide de NavController.createDeepLink().

Créer un lien profond implicite

Un lien profond implicite est une destination spécifique dans une application. Lorsque le lien profond est appelé (par exemple, lorsqu'un utilisateur clique dessus), Android peut ouvrir votre application à la destination correspondante.

Les liens profonds peuvent être mis en correspondance par URI, actions d'intent et types MIME. Vous pouvez indiquer plusieurs types de correspondance pour un seul lien profond. Notez toutefois que la correspondance d'argument de l'URI est prioritaire, suivie de l'action, puis du type MIME.

Voici un exemple de lien profond contenant un URI, une action et un type MIME :

<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>

Vous pouvez également utiliser l'éditeur Navigation pour créer un lien profond implicite vers une destination comme suit :

1. Dans l'onglet Design (Mise en page) de l'éditeur Navigation, sélectionnez la destination du lien profond.
2. Cliquez sur le signe + dans la section Deep Links (Liens profonds) du panneau Attributes (Attributs).

3. Dans la boîte de dialogue Add Deep Link (Ajouter un lien profond) qui s'affiche, saisissez les informations de votre lien profond.

   Remarques :

   • Les URI sans schéma sont censés utiliser les protocoles HTTP ou HTTPS. Par exemple, www.google.com correspond à la fois à http://www.google.com et à https://www.google.com.
   • Les espaces réservés de paramètres de chemin sous la forme {placeholder_name} correspondent à un ou plusieurs caractères. Par exemple, http://www.example.com/users/{id} correspond à http://www.example.com/users/4. Le composant Navigation tente d'analyser les valeurs d'espace réservé dans les types appropriés en faisant correspondre les noms d'espace réservé aux arguments définis pour la destination du lien profond. Si aucun argument portant le même nom n'est défini, un type String par défaut est utilisé pour la valeur de l'argument. Vous pouvez utiliser le caractère générique .* pour établir une correspondance avec zéro ou plusieurs caractères.
   • Les espaces réservés de paramètres de requête peuvent être utilisés à la place des paramètres de chemin d'accès ou conjointement à eux. Par exemple, http://www.example.com/users/{id}?myarg={myarg} correspond à http://www.example.com/users/4?myarg=28.
   • Les espaces réservés de paramètres de requête pour les variables définies avec des valeurs par défaut ou potentiellement nulles ne doivent pas nécessairement correspondre. Par exemple, http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} correspond à http://www.example.com/users/4?arg2=28 ou http://www.example.com/users/4?arg1=7. Ce n'est pas le cas avec les paramètres de chemin d'accès. Par exemple, http://www.example.com/users?arg1=7&arg2=28 ne correspond pas au modèle ci-dessus, car le paramètre de chemin d'accès requis n'est pas fourni.
   • Les paramètres de requête superflus n'affectent pas la correspondance de l'URI du lien profond. Par exemple, http://www.example.com/users/{id} correspond à http://www.example.com/users/4?extraneousParam=7, même si extraneousParam n'est pas défini dans le modèle d'URI.

4. (Facultatif) Cochez la case Auto Verify (Vérification automatique) pour demander à Google de vérifier que vous êtes bien le propriétaire de l'URI. Pour en savoir plus, consultez Valider les liens d'application Android.

5. Cliquez sur Add (Ajouter). Une icône de lien  apparaît au-dessus de la destination sélectionnée pour indiquer qu'elle contient un lien profond.

6. Cliquez sur l'onglet Code pour passer à la vue XML. Un élément <deepLink> imbriqué a été ajouté à la destination :

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

Pour activer les liens profonds implicites, vous devez également ajouter des éléments au fichier manifest.xml de votre application. Ajoutez un seul élément <nav-graph> à une activité qui se réfère à un graphique de navigation existant, comme illustré dans l'exemple suivant :

<?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>

Lors de la création de votre projet, le composant Navigation remplace l'élément <nav-graph> par les éléments <intent-filter> générés pour correspondre à tous les liens profonds du graphique de navigation.

Lors du déclenchement d'un lien profond implicite, l'état de la pile "Retour" varie selon que l'élément Intent implicite a été lancé avec l'option Intent.FLAG_ACTIVITY_NEW_TASK :

• Si l'option est définie, la pile "Retour" de la tâche est effacée et remplacée par la destination du lien profond. Comme pour les liens profonds explicites, lorsque vous imbriquez des graphiques, la destination de départ de chaque niveau d'imbrication, c'est-à-dire la destination de départ de chaque élément <navigation> de la hiérarchie, est également ajoutée à la pile. Cela signifie que lorsqu'un utilisateur appuie sur la pile "Retour" à partir d'une destination de lien profond, il revient dans la pile de navigation comme s'il était arrivé sur votre application à partir de son point d'entrée.
• Si l'option n'est pas définie, vous restez sur la pile de tâches de l'application précédente où le lien profond implicite a été déclenché. Dans ce cas, le bouton "Retour" vous ramène à l'application précédente, tandis que le bouton "Haut" lance la tâche de votre application sur la destination parent dans la hiérarchie de votre graphique de navigation.

Gérer les liens profonds

Il est fortement recommandé de toujours utiliser la valeur launchMode par défaut de standard lorsque vous utilisez Navigation. Lorsque vous utilisez le mode de lancement standard, la fonctionnalité Navigation gère automatiquement les liens profonds en appelant handleDeepLink() pour traiter tous les liens profonds, explicites ou implicites, de Intent. Toutefois, cela ne se produit pas automatiquement si Activity est réutilisé avec un autre launchMode tel que singleTop. Dans ce cas, vous devez appeler manuellement handleDeepLink() dans onNewIntent(), comme illustré dans l'exemple suivant :

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

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

Ressources supplémentaires

Pour en savoir plus sur la navigation, consultez les ressources suivantes.

Exemples

• Exemple de navigation de base avec les composants d'architecture Android

Ateliers de programmation

• Atelier de programmation Navigation

Vidéos

• Android Jetpack : gérer la navigation dans l'interface utilisateur avec le contrôleur de navigation (Google I/O 2018)