Liens d’application Android

Il est souvent souhaitable de connecter un site web et une application mobile pour des liens sur un site web lancent l’application mobile et y affichent du contenu. Le lien d’application, également appelé lien profond, est une technique qui permet à un appareil mobile de répondre à une URI et de lancer du contenu dans une application mobile représentée par l’URI.

Android gère les liens d’application via le système d’intention. Lorsque vous appuyez sur un lien dans un navigateur mobile, le navigateur distribue une intention que Android déléguera à une application inscrite. Ces liens peuvent être basés sur un schéma personnalisé, comme myappname://, ou peuvent utiliser le schéma HTTP ou HTTPS. Par exemple, cliquer sur un lien sur un site web de recettes va ouvrir une application mobile associée à ce site web, puis afficher une recette spécifique à l’utilisateur(-trice). Si plusieurs applications sont enregistrées pour traiter l’intention, Android affiche une boîte de dialogue de désambiguïsation qui demande à l’utilisateur(-trice) quelle application sélectionner pour traiter l’intention. Les utilisateurs qui n’ont pas installé votre application sont dirigés vers du contenu sur votre site web.

Android classifie les liens d’application en trois catégories :

• Les liens profonds sont des URI de n’importe quel schéma qui amène les utilisateurs à du contenu spécifique dans votre application. Lorsqu’un lien profond est cliqué, une boîte de dialogue d’ambiguïté peut s’afficher pour demander à l’utilisateur de sélectionner une application pour gérer le lien profond.
• Les liens web sont des liens profonds qui utilisent le schéma HTTP ou HTTPS. Sur Android 12 et versions ultérieures, un lien web affiche toujours du contenu dans un navigateur web. Sur les versions précédentes d’Android, si une application peut gérer le lien web, une boîte de dialogue de désambiguïsation s’affiche et demande à l’utilisateur de sélectionner une application pour gérer le lien web.
• Les liens d’application Android, disponibles sur l’API 23+, sont des liens web qui utilisent le schéma HTTP ou HTTPS et contiennent l’attribut autoVerify. Cet attribut permet à votre application de devenir le gestionnaire par défaut d’un lien d’application. Par conséquent, lorsque l’on clique sur le lien d’une application, celle-ci s’ouvre sans afficher de boîte de dialogue de désambiguïsation.

NET MAUI Les applications Android peuvent prendre en charge les trois catégories de liens d’application. Toutefois, cet article se concentre sur les liens d’application Android. Pour ce faire, vous devez prouver que vous êtes propriétaire d’un domaine et héberger sur ce domaine un fichier JSON de liens vers des ressources numériques, qui décrit la relation avec votre application. Cela permet à Android de vérifier que l’application qui tente de gérer un URI est propriétaire du domaine de l’URI, afin d’empêcher les applications malveillantes d’intercepter les liens de votre application.

Le processus de gestion des liens de l’application Android dans une application Android .NET MAUI est le suivant :

1. Vérifier la propriété du domaine. Pour plus d’informations, voir Vérifier la propriété du domaine.
2. Créez et hébergez un fichier de liens de ressources numériques sur votre site web. Pour plus d’informations, consultez Créer et héberger un fichier de liens de ressources numériques.
3. Configurez un filtre d’intention dans votre application pour les URI du site web. Pour plus d’informations, voir Configurer le filtre d’intention.
4. Lisez les données de l’intention entrante. Pour plus d’informations, consultez Lire les données de l’intention entrante.

Important

Pour utiliser des liens d’application Android :

• Une version de votre application doit être en direct sur Google Play.
• Un site web compagnon doit être enregistré avec l’application dans la Developer Console de Google. Une fois que l’application est associée à un site web, il est possible d’indexer des URI qui fonctionnent à la fois pour le site web et pour l’application, qui peut alors être affichée dans les résultats de recherche. Pour plus d’informations, consultez App Indexing on Google Search sur support.google.com.

Pour plus d’informations sur les liens d’application Android, consultez Gestion des liens d’application Android.

Vérifier la propriété du domaine

Vous devrez vérifier votre propriété du domaine à partir duquel vous servez des liens d’application dans la console de recherche Google. La vérification de propriété signifie prouver que vous possédez un site web spécifique. Google Search Console prend en charge plusieurs approches de vérification. Pour plus d’informations, consultez Vérifier la propriété de votre site sur support.google.com.

Créez et hébergez un fichier de liens de ressources numériques

Les liens vers les applications Android exigent qu’Android vérifie l’association entre l’application et le site web avant de définir l’application comme gestionnaire par défaut de l’URI. Cette vérification se produit lorsque l’application est installée pour la première fois. Le fichier de liens de ressources numériques est un fichier JSON qui doit être hébergé par le domaine web approprié à l’emplacement suivant : https://domain.name/.well-known/assetlinks.json

Le fichier de ressources numériques contient les métadonnées nécessaires à Android pour vérifier l’association. Le fichier nécessite les paires clé-valeur suivantes :

• namespace – espace de noms de l’application Android.
• package_name – nom du package de l’application Android.
• sha256_cert_fingerprints – les empreintes digitales SHA256 de l’application signée, obtenues à partir de votre .keystore fichier. Pour plus d’informations sur la recherche de la signature de votre magasin de clés, consultez Rechercher la signature de votre magasin de clés.

L’exemple suivant assetlinks.json fichier accorde des droits d’ouverture de lien à une com.companyname.myrecipeapp application Android :

[
   {
      "relation": [
         "delegate_permission/common.handle_all_urls"
      ],
      "target": {
         "namespace": "android_app",
         "package_name": "com.companyname.myrecipeapp",
         "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"
         ]
      }
   }
]

Il est possible d’enregistrer plus d’une empreinte SHA256 pour prendre en charge différentes versions ou builds de votre application. Le fichier assetlinks.json suivant accorde des droits d’ouverture de liens à com.companyname.myrecipeapp et aux com.companyname.mycookingappapplications Android :

[
   {
      "relation": [
         "delegate_permission/common.handle_all_urls"
      ],
      "target": {
         "namespace": "android_app",
         "package_name": "com.companyname.myrecipeapp",
         "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.companyname.mycookingapp",
         "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"
         ]
      }
   }
]

Conseil

Utilisez l’outil Générateur de listes d’instructions et testeur pour vous aider à générer le code JSON correct et à le valider.

Lors de la publication de votre fichier https://domain.name/.well-known/assetlinks.jsonde vérification JSON, vous devez vous assurer que :

• Le fichier est servi avec le type application/jsonde contenu.
• Le fichier doit être accessible via HTTPS, que votre application utilise HTTPS comme schéma.
• Le fichier doit être accessible sans redirection.
• Si les liens de votre application prennent en charge plusieurs domaines, vous devez publier le fichier assetlinks.json sur chaque domaine.

Vous pouvez confirmer que le fichier de ressources numériques est correctement formaté et hébergé en utilisant l’API de liens de ressources numériques de Google :

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=
  https://<WEB SITE ADDRESS>:&relation=delegate_permission/common.handle_all_urls

Pour plus d’informations, consultez Déclarer des associations de sites web sur developer.android.com.

Configurer le filtre d’intention

Un filtre d’intention doit être configuré pour associer un URI, ou un ensemble d’URI, d’un site web à une activité dans votre application Android. Dans .NET MAUI, cela peut être obtenu en ajoutant l’élément IntentFilterAttribute à votre activité. Le filtre d’intention doit déclarer les informations suivantes :

• ActionView – inscrit le filtre d’intention pour répondre aux requêtes d’affichage des informations.
• Categories – le filtre d’intention doit s’inscrire à la fois CategoryDefault et CategoryBrowsable être en mesure de gérer correctement l’URI web.
• DataScheme – le filtre d’intention doit déclarer un schéma personnalisé, et/ou HTTPS et/ou HTTPS.
• DataHost – il s’agit du domaine à partir duquel proviennent les URI.
• DataPathPrefix – il s’agit d’un chemin d’accès facultatif aux ressources sur le site web, qui doit commencer par un /.
• AutoVerify – cela indique à Android de vérifier la relation entre l’application et le site web. Elle doit être définie sur true, sinon Android ne vérifiera pas l’association entre l’application et le site web, et ne définira donc pas votre application comme gestionnaire par défaut pour un URI.

L’exemple suivant montre comment utiliser les IntentFilterAttribute pour gérer les liens à partir de https://www.recipe-app.com/recipes :

using Android.App;
using Android.Content;
using Android.Content.PM;

namespace MyNamespace;

[Activity(
    Theme = "@style/Maui.SplashTheme",
    MainLauncher = true,
    ConfigurationChanges = ConfigChanges.ScreenSize |
        ConfigChanges.Orientation |
        ConfigChanges.UiMode |
        ConfigChanges.ScreenLayout |
        ConfigChanges.SmallestScreenSize |
        ConfigChanges.KeyboardHidden |
        ConfigChanges.Density)]
[IntentFilter(
    new string[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = "https",
    DataHost = "recipe-app.com",
    DataPath = "/recipe",
    AutoVerify = true,)]    
public class MainActivity : MauiAppCompatActivity
{
}

Remarque

Plusieurs schémas et hôtes peuvent être spécifiés dans votre filtre d’intention. Pour plus d’informations, consultez Créer des liens profonds vers le contenu d’application sur developer.android.com.

Android vérifiera chaque hôte identifié dans les filtres d’intention par rapport au fichier d’actifs numériques du site web, avant d’enregistrer l’application en tant que gestionnaire par défaut d’une URI. Tous les filtres d’intention doivent être vérifiés avant qu’Android puisse établir l’application comme gestionnaire par défaut. Une fois que vous avez ajouté un filtre d’intention avec une URI pour le contenu de l’activité, Android est capable d’acheminer toute intention qui a des URI correspondants à votre application au moment de l’exécution.

Il peut également être nécessaire de marquer votre activité comme exportable, afin qu’elle puisse être lancée par d’autres applications. Cela peut être obtenu en ajoutant Exported = true au ActivityAttribute existant. Pour plus d’informations, consultez l’élément Activity sur developer.android.com.

Lorsqu’une intention d’URI web est appelée, Android tente les actions suivantes jusqu’à ce que la requête réussisse :

1. Ouvre l’application préférée pour gérer l’URI.
2. Ouvre la seule application disponible pour gérer l’URI.
3. Permet à l’utilisateur(-trice) de sélectionner une application pour gérer l’URI.

Pour plus d’informations sur les intentions et les filtres d’intention, consultez Intentions et filtres d’intention sur developer.android.com.

Lisez les données de l’intention entrante

Lorsqu’Android lance votre activité par le biais d’un filtre d’intention, vous pouvez utiliser les données fournies par l’intention pour déterminer ce qu’il faut faire. Cette opération doit être effectuée dans un délégué de cycle de vie précoce, idéalement OnCreate. Le ou la OnCreate délégué(e) est appelé(e) lors de la création d’une activité. Pour plus d’informations sur les délégués de cycle de vie, consultez Événements de cycle de vie de la plateforme.

Pour répondre à un(e) délégué(e) de cycle de vie Android appelé(e), appelez la méthode ConfigureLifecycleEvents sur l’objet MauiAppBuilder dans la méthode CreateMauiapp de votre classe MauiProgram. Ensuite, sur l’objet ILifecycleBuilder, appelez la méthode AddAndroid et spécifiez la Action qui inscrit un gestionnaire pour le délégué requis :

using Microsoft.Maui.LifecycleEvents;
using Microsoft.Extensions.Logging;

namespace MyNamespace;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            .ConfigureLifecycleEvents(lifecycle =>
            {
#if ANDROID
                lifecycle.AddAndroid(android =>
                {
                    android.OnCreate((activity, bundle) =>
                    {
                        var action = activity.Intent?.Action;
                        var data = activity.Intent?.Data?.ToString();

                        if (action == Android.Content.Intent.ActionView && data is not null)
                        {
                            Task.Run(() => HandleAppLink(data));
                        }
                    });
                });
#endif
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }

    static void HandleAppLink(string url)
    {
        if (Uri.TryCreate(url, UriKind.RelativeOrAbsolute, out var uri))
            App.Current?.SendOnAppLinkRequestReceived(uri);
    }
}

La Intent.Action propriété récupère l’action associée à l’intention entrante et la Intent.Data propriété récupère les données associées à l’intention entrante. À condition que l’action d’intention soit définie sur ActionView, les données d’intention peuvent être transmises à votre classe App avec la SendOnAppLinkRequestReceived méthode.

Avertissement

Les liens vers les applications constituent un vecteur d’attaque potentiel pour votre application. Veillez donc à valider tous les paramètres de l’URI et à écarter tout URI malformé.

Dans votre classe App, remplacez la méthode OnAppLinkRequestReceived pour recevoir et traiter les données d’intention :

namespace MyNamespace;

public partial class App : Application
{
    ...

    protected override async void OnAppLinkRequestReceived(Uri uri)
    {
        base.OnAppLinkRequestReceived(uri);

        // Show an alert to test that the app link was received.
        await Dispatcher.DispatchAsync(async () =>
        {
            await Windows[0].Page!.DisplayAlert("App link received", uri.ToString(), "OK");
        });

        Console.WriteLine("App link: " + uri.ToString());
    }
}

Dans l’exemple ci-dessus, le remplacement OnAppLinkRequestReceived affiche l’URI du lien d’application. En pratique, le lien de l’application doit amener les utilisateurs directement au contenu représenté par l’URI, sans aucune invite, connexion ou autre interruption. Par conséquent, le remplacement OnAppLinkRequestReceived est l’emplacement à partir duquel appeler la navigation vers le contenu représenté par l’URI.

Tester un lien d’application

À condition que le fichier de ressources numériques soit correctement hébergé, vous pouvez utiliser Android Debug Bridge, adbavec l’outil gestionnaire d’activités, ampour simuler l’ouverture d’un URI pour vous assurer que les liens de votre application fonctionnent correctement. Par exemple, la commande suivante tente d’afficher une activité d’application cible associée à un URI :

adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d YOUR_URI_HERE

Cette commande envoie une intention qu’Android doit diriger vers votre application mobile, qui doit lancer et afficher l’activité enregistrée pour l’URI.

Remarque

Vous pouvez exécuter adb contre un émulateur ou un appareil.

En outre, vous pouvez afficher les politiques de gestion des liens existantes pour les applications installées sur un appareil :

adb shell dumpsys package domain-preferred-apps

Cette commande affiche les informations suivantes :

• Package – Le nom du package de l’application.
• Domaine – les domaines, séparés par des espaces, dont les liens web seront traités par l’application.
• État – l’état actuel de gestion des liens pour l’application. Une valeur de always signifie que l’application a défini AutoVerify sur true et a passé la vérification système. Il est suivi d’un nombre hexadécimal représentant l’enregistrement de la préférence.

Pour plus d’informations sur la adb commande, consultez Android Debug Bridge.

En outre, vous pouvez gérer et vérifier les liens d’application Android via la console Play. Pour plus d’informations, consultez Gérer et vérifier les liens d’application Android sur developer.android.com.

Pour obtenir des conseils de dépannage, consultez Corriger les erreurs d’implémentation courantes sur developer.android.com.