Partager via

Liens universels Apple

Il est souvent souhaitable de connecter un site web et une application mobile afin que les liens sur un site web lancent l’application mobile et affichent du contenu dans l’application mobile. La liaison d’applications, également appelée liaison approfondie, est une technique qui permet à un appareil mobile de répondre à une URL et de lancer du contenu dans une application mobile représentée par l’URL.

Sur les plateformes Apple, les liens profonds sont appelés liens universels. Lorsqu’un utilisateur appuie sur un lien universel, le système redirige le lien directement vers votre application sans routage via Safari ou votre site web. Ces liens peuvent être basés sur un schéma personnalisé, tel que myappname://, ou peuvent utiliser le schéma HTTP ou HTTPS. Par exemple, cliquer sur un lien sur un site web de recette ouvre une application mobile associée à ce site web, puis affiche une recette spécifique à l’utilisateur. Les utilisateurs qui n’ont pas installé votre application sont dirigés vers du contenu sur votre site web. Cet article se concentre sur les liens universels qui utilisent le schéma HTTPS.

Les applications iOS .NET MAUI prennent en charge les liens universels. Cela nécessite l’hébergement d’un fichier JSON de liaisons de ressources numériques sur le domaine, qui décrit la relation avec votre application. Cela permet à Apple de vérifier que l’application qui tente de gérer une URL possède la propriété du domaine URL pour empêcher les applications malveillantes d’intercepter les liens de votre application.

Le processus de gestion des liens universels Apple dans une application .NET MAUI iOS ou Mac Catalyst est le suivant :

Pour plus d’informations, consultez Autoriser les applications et les sites web à lier à votre contenu sur developer.apple.com. Pour plus d’informations sur la définition d’un schéma d’URL personnalisé pour votre application, consultez Définition d’un schéma d’URL personnalisé pour votre application sur developer.apple.com.

Créer et héberger un fichier de domaines associés

Pour associer un site web à votre application, vous devez héberger un fichier de domaine associé sur votre site web. Le fichier de domaine associé est un fichier JSON qui doit être hébergé sur votre domaine à l’emplacement suivant : https://domain.name/.well-known/apple-app-site-association.

Le code JSON suivant montre le contenu d’un fichier de domaines associé classique :

{
    "activitycontinuation": {
        "apps": [ "85HMA3YHJX.com.companyname.myrecipeapp" ]
    },
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "85HMA3YHJX.com.companyname.myrecipeapp",
                "paths": [ "*", "/*" ]
            }
        ]
    }
}

Les clés apps et appID doivent spécifier les identificateurs des applications disponibles pour une utilisation sur le site web. Les valeurs de ces clés sont constituées du préfixe d’identificateur d’application et de l’identificateur de bundle.

Important

Le fichier de domaine associé doit être hébergé en utilisant https avec un certificat valide et sans redirection.

Pour plus d’informations, consultez Prise en charge des domaines associés sur developer.apple.com.

Ajouter le droit des domaines associés à votre application

Après avoir hébergé un fichier de domaine associé sur votre domaine, vous devez ajouter les droits de domaines associés à votre application. Lorsqu’un utilisateur installe votre application, iOS tente de télécharger le fichier de domaine associé et de vérifier les domaines dans votre droit d’utilisation.

Le droit des domaines associés spécifie une liste de domaines auxquels l’application est associée. Ce droit doit être ajouté au fichier Entitlements.plist dans votre application. Pour plus d’informations sur l’ajout d’un droit sur iOS, consultez Droits d’utilisation. Pour plus d’informations sur l’ajout d’un droit sur Mac Catalyst, consultez Droits d’utilisation.

Le droit est défini à l'aide de la clé com.apple.developer.associated-domains, de type Array de String.

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:recipe-app.com</string>
</array>

Pour plus d’informations sur ce droit, consultez le droit des domaines associés sur developer.apple.com.

Vous pouvez également modifier votre fichier projet (.csproj) pour ajouter l'autorisation dans un élément <ItemGroup> :

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios' Or $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">

    <!-- For debugging, use '?mode=developer' for debug to bypass apple's CDN cache -->
    <CustomEntitlements
        Condition="$(Configuration) == 'Debug'"
        Include="com.apple.developer.associated-domains"
        Type="StringArray"
        Value="applinks:recipe-app.com?mode=developer" />

    <!-- Non-debugging, use normal applinks:url value -->
    <CustomEntitlements
        Condition="$(Configuration) != 'Debug'"
        Include="com.apple.developer.associated-domains"
        Type="StringArray"
        Value="applinks:recipe-app.com" />

</ItemGroup>

Dans cet exemple, remplacez applinks:recipe-app.com par la valeur correcte pour votre domaine. Veillez à inclure uniquement le sous-domaine souhaité et le domaine de niveau supérieur. N’incluez pas le chemin et les paramètres de requête, ni une barre oblique finale (/).

Remarque

Dans iOS 14+ et macOS 11+, les applications n’envoient plus de demandes de apple-app-site-association fichiers directement à votre serveur web. Au lieu de cela, ils envoient des demandes à un réseau de distribution de contenu géré par Apple (CDN) dédié aux domaines associés.

Ajouter la fonctionnalité de domaines associés à votre ID d’application

Après avoir ajouté le droit des domaines associés à votre application, vous devez ajouter la fonctionnalité de domaines associés à l’ID d’application de votre application dans votre compte de développeur Apple. Cela est nécessaire, car tous les droits définis dans votre application doivent également être ajoutés en tant que fonctionnalités à l’ID d’application de votre application dans votre compte de développeur Apple.

Pour ajouter la fonctionnalité de domaines associés à votre ID d’application :

  1. Dans un navigateur web, connectez-vous à votre compte développeur Apple et accédez à la page Certificats, ID et profils .

  2. Dans la page Certificats, Identificateurs et profils , sélectionnez l’onglet Identificateurs .

  3. Dans la page Identificateurs , sélectionnez l’ID d’application correspondant à votre application.

  4. Dans la page Modifier votre configuration d’ID d’application , activez la fonctionnalité Domaines associés , puis sélectionnez le bouton Enregistrer :

    Capture d’écran de l’activation de la fonctionnalité de domaines associés dans le portail des développeurs Apple.

  5. Dans la boîte de dialogue Modifier les fonctionnalités de l’application , sélectionnez le bouton Confirmer .

Après avoir mis à jour l’ID d’application de votre application, vous devez générer et télécharger un profil d’approvisionnement mis à jour.

Remarque

Si vous supprimez ultérieurement les droits des domaines associés de votre application, vous devez mettre à jour la configuration de votre ID d’application dans votre compte de développeur Apple.

Lorsqu’un utilisateur active un lien universel, iOS et Mac Catalyst lancent votre application et lui envoient un objet NSUserActivity. Cet objet peut être interrogé pour déterminer la façon dont votre application a été lancée et pour déterminer l’action à entreprendre. Cette opération doit être effectuée dans les délégués de cycle de vie FinishedLaunching et ContinueUserActivity. Le FinishedLaunching délégué est appelé lors du lancement de l’application et le ContinueUserActivity délégué est appelé lorsque l’application est en cours d’exécution ou suspendue. Pour plus d’informations sur les délégués de cycle de vie, consultez les événements de cycle de vie de la plateforme.

Pour réagir à l'appel d'un délégué du cycle de vie iOS, 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 AddiOS et spécifiez le Action qui enregistre 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 IOS || MACCATALYST
                lifecycle.AddiOS(ios =>
                {
                    // Universal link delivered to FinishedLaunching after app launch.
                    ios.FinishedLaunching((app, data) => HandleAppLink(app.UserActivity));

                    // Universal link delivered to ContinueUserActivity when the app is running or suspended.
                    ios.ContinueUserActivity((app, userActivity, handler) => HandleAppLink(userActivity));

                    // Only required if using Scenes for multi-window support.
                    if (OperatingSystem.IsIOSVersionAtLeast(13) || OperatingSystem.IsMacCatalystVersionAtLeast(13))
                    {
                        // Universal link delivered to SceneWillConnect after app launch
                        ios.SceneWillConnect((scene, sceneSession, sceneConnectionOptions)
                            => HandleAppLink(sceneConnectionOptions.UserActivities.ToArray()
                                .FirstOrDefault(a => a.ActivityType == Foundation.NSUserActivityType.BrowsingWeb)));

                        // Universal link delivered to SceneContinueUserActivity when the app is running or suspended
                        ios.SceneContinueUserActivity((scene, userActivity) => HandleAppLink(userActivity));
                    }
                });
#endif
            });

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

        return builder.Build();
    }

#if IOS || MACCATALYST
    static bool HandleAppLink(Foundation.NSUserActivity? userActivity)
    {
        if (userActivity is not null && userActivity.ActivityType == Foundation.NSUserActivityType.BrowsingWeb && userActivity.WebPageUrl is not null)
        {
            HandleAppLink(userActivity.WebPageUrl.ToString());
            return true;
        }
        return false;
    }
#endif

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

Lorsque iOS ouvre votre application à la suite d’un lien universel, l’objet NSUserActivity aura une propriété ActivityType avec la valeur BrowsingWeb. La propriété de l’objet WebPageUrl d’activité contient l’URL à laquelle l’utilisateur souhaite accéder. L’URL peut être transmise à votre App classe avec la SendOnAppLinkRequestReceived méthode.

Remarque

Si vous n’utilisez pas Scene dans votre application pour la prise en charge multi-fenêtre, vous pouvez omettre les gestionnaires de cycle de vie des méthodes Scene.

Dans votre App classe, remplacez la OnAppLinkRequestReceived méthode pour recevoir et traiter l’URL :

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());
    }
}

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!.DisplayAlertAsync("App link received", uri.ToString(), "OK");
        });

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

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

Avertissement

Les liens universels offrent un vecteur d’attaque potentiel dans votre application. Vérifiez donc que vous validez tous les paramètres d’URL et ignorez toutes les URL incorrectes.

Pour plus d’informations, consultez Prise en charge des liens universels dans votre application sur developer.apple.com.

Important

Sur iOS, les liens universels doivent être testés sur un appareil plutôt que sur un simulateur.

Pour tester un lien universel, collez un lien dans votre application Notes et appuyez longuement dessus (sur iOS) ou cliquez dessus (sur macOS) pour découvrir vos choix pour suivre le lien. À condition que les liens universels aient été correctement configurés, le choix d’ouvrir dans l’application et dans Safari s’affiche. Votre choix définit le comportement par défaut sur votre appareil lorsque vous suivez des liens universels à partir de ce domaine. Pour modifier ce choix par défaut, répétez les étapes et faites un autre choix.

Remarque

La saisie de l’URL dans Safari n’ouvre jamais l’application. Au lieu de cela, Safari accepte cette action comme navigation directe. À condition qu’un utilisateur se trouve sur votre domaine après y avoir navigué directement, votre site affiche une bannière pour ouvrir votre application.

Sur iOS, vous pouvez tester vos liens universels avec les tests de diagnostic des domaines associés dans les paramètres du développeur :

  1. Activez le mode développeur dans Paramètres. Pour plus d’informations, consultez Activation du mode développeur sur un appareil sur developer.apple.com.
  2. Dans Paramètres > développeur, faites défiler jusqu’aux liens universels et activez le développement de domaines associés.
  3. Ouvrez Diagnostics et tapez votre URL. Vous recevrez ensuite des commentaires sur la validité du lien pour une application installée.

Souvent, les liens universels non valides sont le résultat de votre applinks configuration incorrecte.

Pour des conseils de dépannage, consultez Débogage des liens universels sur developer.apple.com.