Freigeben über

Universelle Apple-Links

  • Artikel

Es ist häufig wünschenswert, eine Website und eine mobile App so zu verbinden, dass Links auf einer Website die mobile App starten und in dieser Inhalte anzeigen. Die App-Verbindung, die auch als Deep Linkingbezeichnet wird, ist eine Technik, mit der ein mobiles Gerät auf eine URL reagieren und Inhalte in einer mobilen App starten kann, die durch die URL dargestellt wird.

Auf Apple-Plattformen werden Deep-Links als universelle Links bezeichnet. Wenn Benutzer oder Benutzerinnen auf einen universellen Link tippen, leitet das System den Link direkt an Ihre App weiter – ohne Umleitung über Safari oder Ihre Website. Diese Links können auf einem benutzerdefinierten Schema basieren (z. B. myappname://) oder das HTTP- oder HTTPS-Schema nutzen. Wenn Sie z. B. einen Link auf einer Rezeptwebsite auswählen, wird eine mobile App geöffnet, die dieser Website zugeordnet ist, in der ein bestimmtes Rezept angezeigt wird. Benutzer oder Benutzerinnen, die Ihre App nicht installiert haben, werden zu Inhalten auf Ihrer Website weitergeleitet. In diesem Artikel geht es um universelle Links, die das HTTPS-Schema verwenden.

.NET MAUI-Apps für iOS unterstützen universelle Links. Dies erfordert das Hosten einer JSON-Datei mit Links zu digitalen Ressourcen in der Domäne, in der die Beziehung zu Ihrer App beschrieben wird. Dadurch kann Apple überprüfen, ob die App, die versucht, eine URL zu verarbeiten, im Besitz der URL-Domäne ist, um zu verhindern, dass bösartige Apps Ihre App-Links abfangen.

Der Prozess für die Verarbeitung universeller Apple-Links in einer .NET MAUI-App für iOS oder einer Mac Catalyst-App läuft wie folgt ab:

Weitere Informationen finden Sie unter Zulassen von Links von Apps und Websites zu Ihren Inhalten auf developer.apple.com. Informationen zum Definieren eines benutzerdefinierten URL-Schemas für Ihre App finden Sie unter Definieren eines benutzerdefinierten URL-Schemas für Ihre App auf developer.apple.com.

Erstellen und Hosten einer zugeordneten Domänendatei

Um Ihrer App eine Website zuzuordnen, müssen Sie eine zugeordnete Domänendatei auf Ihrer Website hosten. Die zugeordnete Domänendatei ist eine JSON-Datei, die am folgendem Speicherort in Ihrer Domäne gehostet werden muss: https://domain.name/.well-known/apple-app-site-association.

Der folgende JSON-Code zeigt den Inhalt einer typischen zugeordneten Domänendatei:

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

Die Schlüssel apps und appID sollten die App-IDs für die Apps angeben, die für die Verwendung auf der Website verfügbar sind. Die Werte für diese Schlüssel bestehen aus dem Präfix der App-ID und dem Bündelbezeichner.

Wichtig

Die zugeordnete Domänendatei muss mit https mit einem gültigen Zertifikat und ohne Umleitungen gehostet werden.

Weitere Informationen finden Sie unter Unterstützen zugeordneter Domänen auf developer.apple.com.

Hinzufügen der Berechtigung für zugehörige Domänen zu Ihrer App

Nachdem Sie eine zugeordnete Domänendatei in Ihrer Domäne hosten, müssen Sie als Nächstes der App die Berechtigung für zugeordnete Domänen hinzufügen. Wenn Benutzer oder Benutzerinnen Ihre App installieren, versucht iOS, die zugeordnete Domänendatei herunterzuladen und die Domänen in Ihrer Berechtigung zu überprüfen.

Die Berechtigung für zugeordnete Domänen gibt eine Liste der Domänen an, denen die App zugeordnet ist. Diese Berechtigung sollte der Datei Entitlements.plist in Ihrer App hinzugefügt werden. Weitere Informationen zum Hinzufügen einer Berechtigung unter iOS finden Sie unter Berechtigungen. Weitere Informationen zum Hinzufügen einer Berechtigung in Mac Catalyst finden Sie unter Berechtigungen.

Die Berechtigung wird mithilfe des com.apple.developer.associated-domains Schlüssels des Typs Array von String definiert:

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

Weitere Informationen zu dieser Berechtigung finden Sie unter Berechtigung für zugeordnete Domänen auf developer.apple.com.

Alternativ können Sie Ihre Projektdatei (.csproj) ändern, um die Berechtigung in einem <ItemGroup>-Element hinzuzufügen:

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

Ersetzen Sie in diesem Beispiel applinks:recipe-app.com durch den richtigen Wert für Ihre Domäne. Stellen Sie sicher, dass Sie nur die gewünschte Unterdomäne und die Domäne der obersten Ebene einschließen. Fügen Sie keine Pfad- oder Abfragekomponenten oder einen nachgestellten Schrägstrich (/) hinzu.

Hinweis

Unter iOS 14 und höher sowie macOS 11 und höher senden Apps keine Anforderungen für apple-app-site-association-Dateien mehr direkt an Ihren Webserver. Stattdessen senden sie Anforderungen an ein von Apple verwaltetes Content Delivery Network (CDN), das den zugehörigen Domänen zugeordnet ist.

Hinzufügen der zugehörigen Domänenfunktion zu Ihrer App-ID

Nachdem Sie die zugehörigen Domänenberechtigungen zu Ihrer App hinzugefügt haben, müssen Sie der App-ID für Ihre App in Ihrem Apple-Entwicklerkonto die zugehörige Domänenfunktion hinzufügen. Dies ist erforderlich, da alle in Ihrer App definierten Berechtigungen auch als Funktionen zur App-ID für Ihre App in Ihrem Apple-Entwicklerkonto hinzugefügt werden müssen.

So fügen Sie Ihrer App-ID die zugeordnete Domänenfunktion hinzu:

  1. Melden Sie sich in einem Webbrowser bei Ihrem Apple-Entwicklerkonto an, und navigieren Sie zur Seite Zertifikate, IDs & Profile.

  2. Wählen Sie auf der Seite Zertifikate, Bezeichner und Profile die Registerkarte Bezeichner aus.

  3. Wählen Sie auf der Seite Bezeichner die App-ID aus, die Ihrer App entspricht.

  4. Aktivieren Sie auf der Seite App-ID-Konfiguration bearbeiten die Funktion Zugeordnete Domänen, und wählen Sie dann die Schaltfläche Speichern aus:

    Screenshot of enabling the associated domains capability in the Apple Developer Portal.

  5. Wählen Sie im Dialogfeld App-Funktionen ändern die Schaltfläche Bestätigen aus.

Nach dem Aktualisieren der App-ID Ihrer App müssen Sie ein aktualisiertes Bereitstellungsprofil generieren und herunterladen.

Hinweis

Wenn Sie später die zugeordnete Domänenberechtigung aus Ihrer App entfernen, müssen Sie die Konfiguration Ihrer App-ID in Ihrem Apple-Entwicklerkonto aktualisieren.

Wenn ein Benutzer oder eine Benutzerin einen universellen Link aktiviert, starten iOS und Mac Catalyst Ihre App und übermitteln ihr ein NSUserActivity-Objekt. Sie können dieses Objekt abfragen, um zu bestimmen, wie Ihre App gestartet wurde und welche Aktion ausgeführt werden soll. Dies sollte in den Lebenszyklusdelegaten FinishedLaunching und ContinueUserActivity erfolgen. Der FinishedLaunching-Delegat wird aufgerufen, wenn die App gestartet wurde, und der ContinueUserActivity-Delegat wird aufgerufen, wenn die App ausgeführt wird oder angehalten wurde. Weitere Informationen zu Lebenszyklusdelegaten finden Sie unter Plattformlebenszyklusereignisse.

Um auf den Aufruf eines iOS-Lebenszyklus-Delegaten zu reagieren, rufen Sie die ConfigureLifecycleEvents-Methode für das MauiAppBuilder-Objekt in der CreateMauiapp-Methode Ihrer MauiProgram-Klasse auf. Rufen Sie dann im ILifecycleBuilder-Objekt die AddiOS-Methode auf, und geben Sie den Action an, der einen Handler für den erforderlichen Delegaten registriert:

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

Wenn iOS Ihre App als Reaktion auf einen universellen Link öffnet, verfügt das NSUserActivity-Objekt über eine ActivityType-Eigenschaft mit dem Wert BrowsingWeb. Die WebPageUrl-Eigenschaft des Aktivitätsobjekts enthält die URL, auf die der Benutzer oder die Benutzerin zugreifen möchte. Die URL kann mit der SendOnAppLinkRequestReceived-Methode an Ihre App-Klasse übergeben werden.

Hinweis

Wenn Sie in Ihrer App keine Szenen verwenden, um mehrere Fenster zu unterstützen, können Sie die Lebenszyklushandler für die Scene-Methoden weglassen.

Überschreiben Sie in Ihrer App-Klasse die OnAppLinkRequestReceived-Methode, um die URL zu empfangen und zu verarbeiten:

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

Im obigen Beispiel zeigt die OnAppLinkRequestReceived-Überschreibung die App-Link-URL an. In der Praxis sollte der App-Link Benutzer und Benutzerinnen direkt und ohne Unterbrechungen zu den Inhalten weiterleiten, die durch die URL dargestellt sind, ohne dass sie aufgefordert werden, Anmeldeinformationen anzugeben. Daher rufen Sie die Navigation zu den Inhalten, die die URL darstellt, über die OnAppLinkRequestReceived-Überschreibung auf.

Warnung

Universelle Links stellen einen potenziellen Angriffsvektor in Ihrer App dar. Stellen Sie daher sicher, dass Sie alle URL-Parameter überprüfen und alle falsch formatierten URLs ausschließen.

Weitere Informationen finden Sie unter Unterstützen von universellen Links in Ihrer App auf developer.apple.com.

Wichtig

Unter iOS sollten universelle Links auf einem Gerät und nicht in einem Simulator getestet werden.

Um einen universellen Link zu testen, fügen Sie einen Link in Ihre Notes-App ein und halten ihn lange gedrückt (unter iOS) oder klicken bei gedrückter CTRL-Taste darauf (unter macOS), um Ihre Auswahlmöglichkeiten für das Folgen des Links zu ermitteln. Wenn die universellen Links ordnungsgemäß konfiguriert wurden, werden als Optionen das Öffnen in der App und in Safari angezeigt. Ihre Auswahl legt das Standardverhalten auf Ihrem Gerät für das Weiterleiten von universellen Links aus dieser Domäne fest. Wenn Sie diese Standardauswahl ändern möchten, wiederholen Sie die Schritte, und treffen Sie eine andere Auswahl.

Hinweis

Wenn Sie die URL in Safari eingeben, wird nie die App geöffnet. Stattdessen akzeptiert Safari diese Aktion als direkte Navigation. Wenn sich ein Benutzer oder eine Benutzerin nach dem direkten Navigieren in Ihrer Domäne befindet, zeigt Ihre Website ein Banner an, über das Ihre App geöffnet werden kann.

Unter iOS können Sie Ihre universellen Links mit den Diagnosetests für zugehörige Domänen in den Entwicklereinstellungen testen:

  1. Aktivieren Sie den Entwicklermodus in den Einstellungen. Weitere Informationen finden Sie unter Aktivieren des Entwicklermodus auf einem Gerät auf developer.apple.com.
  2. Scrollen Sie in Einstellungen > Entwickler zu Universelle Links, und aktivieren Sie Entwicklung zugehöriger Domänen.
  3. Öffnen Sie Diagnose, und geben Sie Ihre URL ein. Sie erhalten dann Feedback darüber, ob der Link für eine installierte App gültig ist.

Häufig sind universelle Links ungültig, da Ihre applinks falsch konfiguriert sind.

Hinweise zur Problembehandlung finden Sie unter Debuggen universeller Links auf developer.apple.com.