Android-applänkar

Det är ofta önskvärt att ansluta en webbplats och en mobilapp så att länkar på en webbplats startar mobilappen och visar innehåll i mobilappen. Applänkning, som även kallas djuplänkning, är en teknik som gör det möjligt för en mobil enhet att svara på en URI och starta innehåll i en mobilapp som representeras av URI:n.

Android hanterar applänkar via avsiktssystemet. När du trycker på en länk i en mobil webbläsare skickar webbläsaren en avsikt som Android delegerar till en registrerad app. Dessa länkar kan baseras på ett anpassat schema, till exempel myappname://, eller använda HTTP- eller HTTPS-schemat. Om du till exempel klickar på en länk på en receptwebbplats öppnas en mobilapp som är associerad med webbplatsen och sedan visar ett specifikt recept för användaren. Om det finns fler än en app registrerad för att hantera avsikten visar Android en disambiguationsdialogruta som ber användaren vilken app som ska väljas för att hantera avsikten. Användare som inte har din app installerad tas till innehåll på din webbplats.

Android klassificerar applänkar i tre kategorier:

• Djupa länkar är URI:er för alla scheman som tar användare till specifikt innehåll i din app. När du klickar på en djuplänk kan en disambiguationsdialogruta visas som ber användaren att välja en app för att hantera den djupa länken.
• Webblänkar är djuplänkar som använder HTTP- eller HTTPS-schemat. På Android 12 och senare visar en webblänk alltid innehåll i en webbläsare. Om en app kan hantera webblänken i tidigare versioner av Android visas en disambiguationsdialogruta som ber användaren att välja en app för att hantera webblänken.
• Android-applänkar, som är tillgängliga på API 23+, är webblänkar som använder HTTP- eller HTTPS-schemat och innehåller autoVerify attributet. Med det här attributet kan din app bli standardhanterare för en applänk. När du klickar på en applänk öppnas därför appen utan att en dialogruta visas.

.NET MAUI Android-appar kan stödja alla tre kategorier av applänkar. Den här artikeln fokuserar dock på Android-applänkar. Detta kräver att du bevisar ägarskapet för en domän och är värd för en JSON-fil för digitala tillgångar på domänen, som beskriver relationen med din app. Detta gör det möjligt för Android att kontrollera att appen som försöker hantera en URI har ägarskap för URI:er-domänen för att förhindra att skadliga appar fångar upp dina applänkar.

Processen för att hantera Android-applänkar i en .NET MAUI Android-app är följande:

1. Kontrollera domänägarskapet. Mer information finns i Verifiera domänägarskap.
2. Skapa och vara värd för en länkfil för digitala tillgångar på din webbplats. Mer information finns i Skapa och vara värd för en länkfil för digitala tillgångar.
3. Konfigurera ett avsiktsfilter i din app för webbplatsens URI:er. Mer information finns i Konfigurera avsiktsfiltret.
4. Läs data från den inkommande intentionen. Mer information finns under Läs data från den inkommande intentionen.

Viktigt!

Så här använder du Android-applänkar:

• En version av din app måste vara live på Google Play.
• En tillhörande webbplats måste registreras mot appen i Googles utvecklarkonsol. När appen är associerad med en webbplats kan URI:er indexeras som fungerar för både webbplatsen och appen, som sedan kan hanteras i sökresultat. Mer information finns i Appindexering på Google Search på support.google.com.

Mer information om Android-applänkar finns i Hantera Android-applänkar.

Verifiera domänägarskap

Du måste verifiera ditt ägarskap för domänen som du hanterar applänkar från i Google Search Console. Ägarskapsverifiering innebär att bevisa att du äger en specifik webbplats. Google Search Console stöder flera verifieringsmetoder. Mer information finns i Verifiera webbplatsägarskapet på support.google.com.

Skapa och vara värd för en länkfil för digitala tillgångar

Android-applänkar kräver att Android verifierar associationen mellan appen och webbplatsen innan du anger appen som standardhanterare för URI:n. Den här verifieringen sker när appen först installeras. Filen med länkar till digitala tillgångar är en JSON-fil som måste vara värd för den relevanta webbdomänen på följande plats: https://domain.name/.well-known/assetlinks.json.

Den digitala tillgångsfilen innehåller de metadata som krävs för att Android ska kunna verifiera associationen. Filen kräver följande nyckel/värde-par:

• namespace – namnområdet för Android-appen.
• package_name – paketnamnet för Android-appen.
• sha256_cert_fingerprints – SHA256-fingeravtrycken för den signerade appen som hämtats från din .keystore fil. Information om hur du hittar nyckelarkivets signatur finns i Hitta nyckelarkivets signatur.

Följande exempel assetlinks.json fil ger länköppningsrättigheter till en 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"
         ]
      }
   }
]

Det går att registrera fler än ett SHA256-fingeravtryck för att stödja olika versioner eller versioner av din app. Följande assetlinks.json-fil ger länköppningsrättigheter till både com.companyname.myrecipeapp Android-appar och com.companyname.mycookingapp Android-appar:

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

Tips/Råd

Använd verktyget Generator och testverktyg för instruktionslista för att generera rätt JSON och för att verifiera den.

När du publicerar JSON-verifieringsfilen till https://domain.name/.well-known/assetlinks.json, måste du se till att:

• Filen hanteras med innehållstypen application/json.
• Filen måste vara tillgänglig via HTTPS, oavsett om din app använder HTTPS som schema.
• Filen måste vara tillgänglig utan omdirigeringar.
• Om dina applänkar stöder flera domäner måste du publicera assetlinks.json-filen på varje domän.

Du kan bekräfta att filen med digitala tillgångar är korrekt formaterad och värdhanterad med hjälp av Googles API för digitala tillgångslänkar:

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

Mer information finns i Deklarera webbplatsassociationer på developer.android.com.

Konfigurera avsiktsfiltret

Ett avsiktsfilter måste konfigureras som mappar en URI eller uppsättning URI:er från en webbplats till en aktivitet i din Android-app. I .NET MAUI kan du göra detta genom att lägga till IntentFilterAttribute till din aktivitet. Avsiktsfiltret måste deklarera följande information:

• ActionView – detta registrerar avsiktsfiltret för att svara på begäranden om att visa information.
• Categories – avsiktsfiltret bör registrera både CategoryDefault och CategoryBrowsable för att kunna hantera webb-URI:n på rätt sätt.
• DataScheme – avsiktsfiltret måste deklarera ett anpassat schema och/eller HTTPS och/eller HTTPS.
• DataHost – det här är den domän som URI:er kommer från.
• DataPathPrefix – Det här är en valfri sökväg till resurser på webbplatsen, som måste börja med en /.
• AutoVerify – Detta talar om för Android att verifiera relationen mellan appen och webbplatsen. Det måste anges till true annars verifierar Android inte associationen mellan appen och webbplatsen och anger därför inte appen som standardhanterare för en URI.

I följande exempel visas hur du använder IntentFilterAttribute för att hantera länkar från 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
{
}

Anmärkning

Flera scheman och värdar kan anges i avsiktsfiltret. Mer information finns i Skapa djuplänkar till appinnehåll på developer.android.com.

Android verifierar varje värd som identifieras i avsiktsfiltren mot filen med digitala tillgångar på webbplatsen innan appen registreras som standardhanterare för en URI. Alla avsiktsfilter måste godkännas för verifiering innan Android kan etablera appen som standardhanterare. När du har lagt till ett avsiktsfilter med en URI för aktivitetsinnehåll kan Android dirigera alla avsikter som har matchande URI:er till din app vid körning.

Det kan också vara nödvändigt att markera din aktivitet som exporterbar, så att aktiviteten kan startas av andra appar. Detta kan uppnås genom att lägga Exported = true till i den befintliga ActivityAttribute. Mer information finns i Aktivitetselement på developer.android.com.

När en webb-URI-avsikt anropas försöker Android utföra följande åtgärder tills begäran lyckas:

1. Öppnar den föredragna appen för att hantera URI:n.
2. Öppnar den enda tillgängliga appen för att hantera URI:n.
3. Tillåter att användaren väljer en app för att hantera URI:n.

Mer information om avsikter och avsiktsfilter finns i Avsikter och avsiktsfilter på developer.android.com.

Läs data från den inkommande intenten

När Android startar din aktivitet via ett avsiktsfilter kan du använda de data som tillhandahålls av avsikten för att avgöra vad du ska göra. Detta bör utföras i en delegering i ett tidigt skede av livscykeln, helst OnCreate. Ombudet OnCreate anropas när en aktivitet skapas. Mer information om livscykeldelegater finns i Händelser för plattformslivscykel.

Om du vill svara på att en Android-livscykeldelegat anropas, anropar du ConfigureLifecycleEvents-metoden på MauiAppBuilder-objektet i CreateMauiapp-metoden i din MauiProgram-klass. Anropa sedan AddAndroid-metoden på ILifecycleBuilder-objektet och specificera Action, som registrerar en hanterare för den obligatoriska delegaten.

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));
                        }
                    });
                    android.OnNewIntent((activity, intent) =>
                    {
                        var action = intent?.Action;
                        var data = 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);
    }
}

Egenskapen Intent.Action hämtar åtgärden som är associerad med den inkommande avsikten, och egenskapen Intent.Data hämtar den data som är associerad med den inkommande avsikten. Förutsatt att avsiktsåtgärden är inställd på ActionViewkan avsiktsdata skickas till klassen App med SendOnAppLinkRequestReceived metoden .

Varning

Applänkar erbjuder en potentiell attackvektor i din app, så se till att du verifierar alla URI-parametrar och tar bort eventuella felaktiga URI:er.

I klassen App åsidosätter du OnAppLinkRequestReceived metoden för att ta emot och bearbeta avsiktsdata:

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

I exemplet ovan visar åsidosättningen OnAppLinkRequestReceived applänkens URI. I praktiken bör applänken ta användarna direkt till det innehåll som representeras av URI:n, utan några uppmaningar, inloggningar eller andra avbrott. OnAppLinkRequestReceived Därför är åsidosättningen den plats från vilken navigeringen ska anropas till innehållet som representeras av URI:n.

Testa en applänk

Förutsatt att den digitala tillgångsfilen är korrekt hostad kan du använda Android Debug Bridge (ADB), adb tillsammans med verktyget Aktivitetshanteraren, am för att simulera att öppna en URI och på så sätt säkerställa att applänkarna fungerar korrekt. Följande kommando försöker till exempel visa en målappaktivitet som är associerad med en URI:

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

Det här kommandot skickar en avsikt som Android ska dirigera till din mobilapp, som ska starta och visa den aktivitet som registrerats för URI:n.

Anmärkning

Du kan köra adb mot en emulator eller en enhet.

Dessutom kan du visa befintliga länkhanteringsprinciper för de appar som är installerade på en enhet:

adb shell dumpsys package domain-preferred-apps

Det här kommandot visar följande information:

• Paket – appens paketnamn.
• Domän – domänerna, avgränsade med blanksteg, vars webblänkar hanteras av appen.
• Status – aktuell länkhanteringsstatus för appen. Värdet always innebär att appen har ställt in AutoVerify till true och har klarat systemverifieringen. Det följs av ett hexadecimalt tal som representerar en preferenspost.

Mer information om kommandot finns i adbAndroid Debug Bridge.

Dessutom kan du hantera och verifiera Android-applänkar via Play Console. Mer information finns i Hantera och verifiera Android-applänkar på developer.android.com.

Felsökningsråd finns i Åtgärda vanliga implementeringsfel på developer.android.com.