Android-App-Links

Es ist häufig wünschenswert, eine Website und eine mobile App zu verbinden, damit Links auf einer Website die mobile App starten und Inhalte in der mobilen App anzeigen. App-Verknüpfungen, die auch als Deep-Linking bezeichnet werden, ist eine Technik, mit der ein mobiles Gerät auf einen URI reagieren und Inhalte in einer mobilen App starten kann, die durch den URI dargestellt wird.

Android verarbeitet App-Links über das Intent-System. Wenn Sie in einem mobilen Browser auf einen Link tippen, sendet der Browser eine Absicht, die Android an eine registrierte App delegieren wird. Diese Links können auf einem benutzerdefinierten Schema basieren, wie myappname://, oder das HTTP- oder HTTPS-Protokoll verwenden. Wenn Sie z. B. auf einen Link auf einer Rezeptwebsite klicken, öffnen Sie eine mobile App, die dieser Website zugeordnet ist, und zeigen dann dem Benutzer ein bestimmtes Rezept an. Wenn mehrere Apps für die Verarbeitung der Absicht registriert sind, zeigt Android ein Mehrdeutigkeitsdialogfeld an, in dem der Benutzer gefragt wird, welche App zur Behandlung der Absicht ausgewählt werden soll. Benutzer, die Ihre App nicht installiert haben, werden zu Inhalten auf Ihrer Website weitergeleitet.

Android klassifiziert App-Links in drei Kategorien:

• Deep-Links sind URIs jedes Schemas, das Benutzer zu bestimmten Inhalten in Ihrer App führt. Wenn auf einen Deep-Link geklickt wird, wird möglicherweise ein Mehrdeutigkeitsdialogfeld angezeigt, in dem der Benutzer aufgefordert wird, eine App zum Behandeln des Deep-Links auszuwählen.
• Weblinks sind Deep-Links , die das HTTP- oder HTTPS-Schema verwenden. Unter Android 12 und höher zeigt ein Weblink immer Inhalte in einem Webbrowser an. Wenn eine App in früheren Versionen von Android den Weblink verarbeiten kann, wird ein Mehrdeutigkeitsdialogfeld angezeigt, in dem der Benutzer aufgefordert wird, eine App zum Behandeln des Weblinks auszuwählen.
• Android-App-Links, die auf API 23+ verfügbar sind, sind Weblinks, die das HTTP- oder HTTPS-Schema verwenden und das autoVerify Attribut enthalten. Mit diesem Attribut kann Ihre App zum Standardhandler für einen App-Link werden. Wenn auf einen App-Link geklickt wird, wird die App geöffnet, ohne dass ein Mehrdeutigkeitsdialogfeld angezeigt wird.

.NET MAUI Android-Apps können alle drei Kategorien von App-Links unterstützen. Dieser Artikel konzentriert sich jedoch auf Android-App-Links. Dies erfordert den Nachweis des Besitzes einer Domain sowie das Hosten einer Datei für digitale Asset-Links vom Typ JSON auf der Domain, die die Beziehung zu Ihrer App beschreibt. Auf diese Weise kann Android überprüfen, ob die App, die versucht, einen URI zu verarbeiten, Besitzer der URIs-Domäne ist, um zu verhindern, dass bösartige Apps Ihre App-Links abfangen.

Der Prozess für die Behandlung von Android-App-Links in einer .NET MAUI Android-App lautet wie folgt:

1. Überprüfen des Domänenbesitzes. Weitere Informationen finden Sie unter Überprüfen des Domänenbesitzes.
2. Erstellen und hosten Sie eine Datei für Digital Asset Links auf Ihrer Website. Weitere Informationen finden Sie unter Erstellen und Hosten einer Verknüpfungsdatei für digitale Objekte.
3. Konfigurieren Sie einen Absichtsfilter in Ihrer App für die Website-URIs. Weitere Informationen finden Sie unter Konfigurieren des Intent-Filters.
4. Lesen Sie die Daten aus der eingehenden Absicht. Weitere Informationen finden Sie unter Lesen der Daten aus der eingehenden Intention.

Von Bedeutung

So verwenden Sie Android-App-Links:

• Eine Version Ihrer App muss auf Google Play live sein.
• Eine Begleitwebsite muss bei der App in der Entwicklerkonsole von Google registriert werden. Sobald die App einer Website zugeordnet ist, können URIs indiziert werden, die sowohl für die Website als auch für die App funktionieren, die dann in Suchergebnissen bereitgestellt werden kann. Weitere Informationen finden Sie unter App-Indizierung bei Google Search auf support.google.com.

Weitere Informationen zu Android-App-Links finden Sie unter Behandeln von Android-App-Links.

Überprüfen des Domänenbesitzes

Sie müssen den Besitz der Domäne überprüfen, über die Sie App-Links in der Google Search Console verwenden. Die Besitzüberprüfung bedeutet, dass Sie über eine bestimmte Website verfügen. Google Search Console unterstützt mehrere Überprüfungsansätze. Weitere Informationen finden Sie unter Überprüfen des Websitebesitzes auf support.google.com.

Erstellen und Hosten einer Datei mit digitalen Ressourcenlinks

Android-App-Links erfordern, dass Android die Zuordnung zwischen der App und der Website überprüft, bevor Sie die App als Standardhandler für den URI festlegen. Diese Überprüfung erfolgt, wenn die App zum ersten Mal installiert wird. Die digitale Asset-Links-Datei ist eine JSON-Datei, die auf der relevanten Webdomain am folgenden Speicherort gehostet werden muss: https://domain.name/.well-known/assetlinks.json.

Die Datei für digitale Ressourcen enthält die Metadaten, die für Android erforderlich sind, um die Zuordnung zu überprüfen. Für die Datei sind die folgenden Schlüsselwertpaare erforderlich:

• namespace – der Namespace der Android-App.
• package_name – der Paketname der Android-App.
• sha256_cert_fingerprints – die SHA256-Fingerabdrücke der signierten App, die aus Ihrer .keystore Datei abgerufen werden. Informationen zum Ermitteln der Signatur Ihres Schlüsselspeichers finden Sie unter "Suchen der Signatur Ihres Schlüsselspeichers".

Das folgende Beispiel assetlinks.json Datei gewährt Linköffnungsrechten für eine com.companyname.myrecipeapp Android-App:

[
   {
      "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"
         ]
      }
   }
]

Es ist möglich, mehr als einen SHA256-Fingerabdruck zu registrieren, um verschiedene Versionen oder Builds Ihrer App zu unterstützen. Die folgende assetlinks.json Datei gewährt Linköffnungsrechte sowohl für die Android-Apps als auch für die com.companyname.myrecipeapp- und com.companyname.mycookingapp-Apps.

[
   {
      "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"
         ]
      }
   }
]

Tipp

Verwenden Sie das Tool "Anweisungslisten-Generator und Tester", um den richtigen JSON-Code zu generieren und zu überprüfen.

Wenn Sie Ihre JSON-Überprüfungsdatei auf https://domain.name/.well-known/assetlinks.json veröffentlichen, müssen Sie Folgendes sicherstellen:

• Die Datei wird mit dem Inhaltstyp application/jsonbereitgestellt.
• Auf die Datei muss über HTTPS zugegriffen werden, unabhängig davon, ob Ihre App HTTPS als Schema verwendet.
• Auf die Datei muss ohne Umleitungen zugegriffen werden.
• Wenn Ihre App mehrere Domänen unterstützt, müssen Sie die assetlinks.json Datei in jeder Domäne veröffentlichen.

Sie können bestätigen, dass die Datei für digitale Objekte ordnungsgemäß formatiert und gehostet wird, indem Sie die API für digitale Objekte von Google verwenden:

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

Weitere Informationen finden Sie unter Deklarieren von Websitezuordnungen auf developer.android.com.

Konfigurieren Sie den Intent-Filter

Ein Absichtsfilter muss konfiguriert werden, der einen URI oder einen Satz von URIs von einer Website zu einer Aktivität in Ihrer Android-App zuordnet. In .NET MAUI kann dies durch Hinzufügen des IntentFilterAttribute zu Ihrer bestehenden Aktivität erreicht werden. Der Intent-Filter muss die folgenden Informationen deklarieren:

• ActionView – Dadurch wird der Absichtsfilter registriert, um auf Anforderungen zum Anzeigen von Informationen zu reagieren.
• Categories – Der Intent-Filter sollte sowohl CategoryDefault als auch CategoryBrowsable registrieren, um den Web-URI ordnungsgemäß verarbeiten zu können.
• DataScheme - Der Intent-Filter muss ein benutzerdefiniertes Schema und/oder HTTPS und/oder HTTPS deklarieren.
• DataHost – dies ist die Domäne, aus der URIs stammen.
• DataPathPrefix - Dies ist ein optionaler Pfad zu Ressourcen auf der Website, der mit einem / beginnen muss.
• AutoVerify – Dies weist Android an, die Beziehung zwischen der App und der Website zu überprüfen. Es muss auf true gesetzt werden, sonst überprüft Android die Zuordnung zwischen der App und der Website nicht und Ihre App wird daher nicht als Standardverwalter für eine URI festgelegt.

Das folgende Beispiel zeigt, wie Sie den IntentFilterAttribute verwenden, um Verknüpfungen von https://www.recipe-app.com/recipes zu behandeln.

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

Hinweis

Mehrere Schemas und Hosts können in Ihrem Intent-Filter angegeben werden. Weitere Informationen finden Sie unter Erstellen von Deep Links zu App-Inhalten auf developer.android.com.

Android überprüft jeden Host, der in den Absichtsfiltern anhand der Datei für digitale Objekte auf der Website identifiziert wird, bevor die App als Standardhandler für einen URI registriert wird. Alle Absichtsfilter müssen die Überprüfung bestehen, bevor Android die App als Standardhandler einrichten kann. Nachdem Sie einen Intent-Filter mit einem URI für Aktivitätsinhalte hinzugefügt haben, kann Android alle Absichten weiterleiten, die übereinstimmende URIs zur Laufzeit an Ihre App haben.

Es kann auch erforderlich sein, Ihre Aktivität als exportierbar zu kennzeichnen, damit Ihre Aktivität von anderen Apps gestartet werden kann. Dies kann durch Hinzufügen Exported = true zum vorhandenen ActivityAttributeerreicht werden. Weitere Informationen finden Sie unter "Activity"-Element für developer.android.com.

Wenn eine Web-URI-Absicht aufgerufen wird, versucht Android die folgenden Aktionen, bis die Anforderung erfolgreich ist:

1. Öffnet die bevorzugte App, um den URI zu behandeln.
2. Öffnet die einzige verfügbare App zum Behandeln des URI.
3. Ermöglicht es dem Benutzer, eine App zum Behandeln des URI auszuwählen.

Weitere Informationen zu Intents und Intent-Filtern finden Sie auf Intents and Intent Filters auf developer.android.com.

Lesen der Daten aus der eingehenden Intention

Wenn Android Ihre Aktivität über einen Intent-Filter startet, können Sie die von der Absicht bereitgestellten Daten verwenden, um zu bestimmen, was zu tun ist. Dies sollte in einem frühen Lebenszyklusdelegat durchgeführt werden, idealerweise OnCreate. Die OnCreate Stellvertretung wird aufgerufen, wenn eine Aktivität erstellt wird. Weitere Informationen zu Lebenszyklusdelegaten finden Sie unter Plattformlebenszyklusereignisse.

Um auf einen aufgerufenen Android-Lebenszyklusdelegat zu reagieren, rufen Sie die ConfigureLifecycleEvents Methode für das MauiAppBuilder Objekt in der CreateMauiapp Methode Ihrer MauiProgram Klasse auf. Rufen Sie dann die Methode AddAndroid im ILifecycleBuilder Objekt auf und spezifizieren Sie das Action, das 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 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);
    }
}

Die Intent.Action Eigenschaft ruft die Aktion ab, die der eingehenden Absicht zugeordnet ist, und die Intent.Data Eigenschaft ruft die Daten ab, die mit dem eingehenden Intent verknüpft sind. Sofern die Absichtsaktion auf ActionView festgelegt ist, können die Absichtsdaten mit der Methode SendOnAppLinkRequestReceived an die Klasse App übergeben werden.

Warnung

App-Links bieten einen potenziellen Angriffsvektor in Ihrer App. Stellen Sie daher sicher, dass Sie alle URI-Parameter überprüfen und alle falsch formatierten URIs verwerfen.

Überschreiben Sie in Ihrer App Klasse die OnAppLinkRequestReceived Methode, um die Absichtsdaten 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 den App-Link-URI an. In der Praxis sollte der App-Link Benutzer direkt zu den inhalten führen, die durch den URI dargestellt werden, ohne Aufforderungen, Anmeldungen oder andere Unterbrechungen. Daher ist die OnAppLinkRequestReceived Überschreibung der Speicherort, von dem aus die Navigation zum durch den URI dargestellten Inhalt aufgerufen werden soll.

Testen eines App-Links

Sofern die digitale Asset-Datei ordnungsgemäß gehostet wird, können Sie die Android Debug Bridge, adbmit dem Aktivitäts-Manager-Tool, amverwenden, um das Öffnen einer URI zu simulieren und sicherzustellen, dass Ihre App-Verknüpfungen ordnungsgemäß funktionieren. Der folgende Befehl versucht beispielsweise, eine Ziel-App-Aktivität anzuzeigen, die einem URI zugeordnet ist:

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

Dieser Befehl sendet eine Absicht, die Android an Ihre mobile App weiterleiten soll, wodurch die für den URI registrierte Aktivität gestartet und angezeigt werden soll.

Hinweis

Sie können adb auf einem Emulator oder einem Gerät ausführen.

Darüber hinaus können Sie die vorhandenen Richtlinien für die Verknüpfungsverarbeitung für die auf einem Gerät installierten Apps anzeigen:

adb shell dumpsys package domain-preferred-apps

Mit diesem Befehl werden die folgenden Informationen angezeigt:

• Paket – der Paketname der App.
• Domäne – die Domänen, getrennt durch Leerzeichen, deren Weblinks von der App behandelt werden.
• Status – der aktuelle Status der Verknüpfungsbehandlung für die App. Ein Wert von always bedeutet, dass die App AutoVerify auf true gesetzt hat und die Systemüberprüfung bestanden hat. Es folgt eine hexadezimale Zahl, die die Aufzeichnung der Präferenz darstellt.

Weitere Informationen zum adb Befehl finden Sie unter Android Debug Bridge.

Darüber hinaus können Sie Android-App-Links über die Play Console verwalten und überprüfen. Weitere Informationen finden Sie unter Verwalten und Überprüfen von Android-App-Links auf developer.android.com.

Informationen zur Problembehandlung finden Sie unter Beheben häufiger Implementierungsfehler auf developer.android.com.