Collegamenti alle app Android
Spesso è consigliabile connettere un sito Web e un'app per dispositivi mobili in modo che i collegamenti in un sito Web avviino l'app per dispositivi mobili e visualizzino il contenuto nell'app per dispositivi mobili. Il collegamento delle app, noto anche come deep linking, è una tecnica che consente a un dispositivo mobile di rispondere a un URI e avviare contenuto in un'app per dispositivi mobili rappresentata dall'URI.
Android gestisce i collegamenti delle app tramite il sistema di finalità. Quando si tocca un collegamento in un browser per dispositivi mobili, il browser invierà una finalità che Android delega a un'app registrata. Questi collegamenti possono essere basati su uno schema personalizzato, ad esempio myappname://, oppure possono usare lo schema HTTP o HTTPS. Ad esempio, facendo clic su un collegamento in un sito Web della ricetta si aprirà un'app per dispositivi mobili associata al sito Web e quindi viene visualizzata una ricetta specifica per l'utente. Se sono presenti più app registrate per gestire la finalità, Android visualizzerà una finestra di dialogo di ambiguità che chiede all'utente quale app selezionare per gestire la finalità. Gli utenti che non hanno installato l'app vengono portati al contenuto nel sito Web.
Android classifica i collegamenti dell'app in tre categorie:
- I collegamenti diretti sono URI di qualsiasi schema che porta gli utenti a contenuti specifici nell'app. Quando si fa clic su un collegamento diretto, potrebbe essere visualizzata una finestra di dialogo di ambiguità che chiede all'utente di selezionare un'app per gestire il collegamento diretto.
- I collegamenti Web sono collegamenti diretti che usano lo schema HTTP o HTTPS. In Android 12 e versioni successive, un collegamento Web mostra sempre il contenuto in un Web browser. Nelle versioni precedenti di Android, se un'app può gestire il collegamento Web, verrà visualizzata una finestra di dialogo di disambiguazione che chiede all'utente di selezionare un'app per gestire il collegamento Web.
- I collegamenti alle app Android, disponibili nell'API 23+, sono collegamenti Web che usano lo schema HTTP o HTTPS e contengono l'attributo
autoVerify. Questo attributo consente all'app di diventare il gestore predefinito per un collegamento all'app. Pertanto, quando si fa clic su un collegamento all'app, l'app viene aperta senza visualizzare una finestra di dialogo di disambiguazione.
Le app ANDROID .NET MAUI possono supportare tutte e tre le categorie di collegamenti alle app. Tuttavia, questo articolo è incentrato sui collegamenti alle app Android. Ciò richiede la dimostrazione della proprietà di un dominio e l'hosting di un file JSON di file di collegamenti di asset digitali nel dominio, che descrive la relazione con l'app. Ciò consente ad Android di verificare che l'app che tenta di gestire un URI abbia la proprietà del dominio URI per impedire che le app dannose intercettano i collegamenti dell'app.
Il processo per la gestione dei collegamenti alle app Android in un'app .NET MAUI Android è il seguente:
- Verificare la proprietà del dominio. Per altre informazioni, vedere Verificare la proprietà del dominio.
- Creare e ospitare un file di collegamenti di asset digitali nel sito Web. Per altre informazioni, vedere Creare e ospitare un file di collegamenti ad asset digitali.
- Configurare un filtro finalità nell'app per gli URI del sito Web. Per altre informazioni, vedere Configurare il filtro finalità.
- Leggere i dati dalla finalità in ingresso. Per altre informazioni, vedere Leggere i dati dalla finalità in ingresso.
Importante
Per usare i collegamenti alle app Android:
- Una versione dell'app deve essere disponibile su Google Play.
- Un sito Web complementare deve essere registrato nell'app nella Console per sviluppatori di Google. Dopo che l'app è associata a un sito Web, è possibile indicizzare gli URI che funzionano sia per il sito Web che per l'app, che possono quindi essere serviti nei risultati della ricerca. Per altre informazioni, vedere Indicizzazione delle app su Google Search su support.google.com.
Per altre informazioni sui collegamenti alle app Android, vedere Gestione dei collegamenti alle app Android.
Verifica proprietà dominio
Dovrai verificare la tua proprietà del dominio da cui stai servendo i collegamenti alle app in Google Search Console. La verifica della proprietà significa dimostrare di essere proprietari di un sito Web specifico. Google Search Console supporta più approcci di verifica. Per altre informazioni, vedere Verificare la proprietà del sito in support.google.com.
Creare e ospitare un file di collegamenti di asset digitali
I collegamenti alle app Android richiedono che Android verifichi l'associazione tra l'app e il sito Web prima di impostare l'app come gestore predefinito per l'URI. Questa verifica si verifica quando l'app viene installata per la prima volta. Il file di collegamenti degli asset digitali è un file JSON che deve essere ospitato dal dominio Web pertinente nel percorso seguente: https://domain.name/.well-known/assetlinks.json.
Il file di asset digitale contiene i metadati necessari per Android per verificare l'associazione. Il file richiede le coppie chiave-valore seguenti:
namespace- spazio dei nomi dell'app Android.package_name: nome del pacchetto dell'app Android.sha256_cert_fingerprints- Le impronte digitali SHA256 dell'app firmata, ottenute dal.keystorefile. Per informazioni sulla ricerca della firma dell'archivio chiavi, vedere Trovare la firma dell'archivio chiavi.
L'esempio seguente assetlinks.json file concede diritti di apertura dei collegamenti a un'app com.companyname.myrecipeapp 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"
]
}
}
]
È possibile registrare più di un'impronta digitale SHA256 per supportare versioni o build diverse dell'app. Il file di assetlinks.json seguente concede i diritti di apertura dei collegamenti alle com.companyname.myrecipeapp app e com.companyname.mycookingapp 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"
]
}
}
]
Suggerimento
Usare lo strumento Generatore elenco istruzioni e tester per generare il codice JSON corretto e per convalidarlo.
Quando si pubblica il file di verifica JSON in https://domain.name/.well-known/assetlinks.json, è necessario assicurarsi che:
- Il file viene fornito con il tipo di
application/jsoncontenuto . - Il file deve essere accessibile tramite HTTPS, indipendentemente dal fatto che l'app usi HTTPS come schema.
- Il file deve essere accessibile senza reindirizzamenti.
- Se i collegamenti dell'app supportano più domini, è necessario pubblicare il file assetlinks.json in ogni dominio.
È possibile verificare che il file di asset digitali sia formattato correttamente e ospitato usando l'API dei collegamenti agli asset digitali di Google:
https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=
https://<WEB SITE ADDRESS>:&relation=delegate_permission/common.handle_all_urls
Per altre informazioni, vedere Dichiarare le associazioni di siti Web in developer.android.com.
Configurare il filtro finalità
È necessario configurare un filtro finalità che esegue il mapping di un URI o di un set di URI da un sito Web a un'attività nell'app Android. In .NET MAUI questo risultato può essere ottenuto aggiungendo l'oggetto all'attività IntentFilterAttribute . Il filtro finalità deve dichiarare le informazioni seguenti:
- ActionView : verrà registrato il filtro finalità per rispondere alle richieste per visualizzare le informazioni.
- Categories - Il filtro finalità deve registrare sia CategoryDefault che CategoryBrowsable per essere in grado di gestire correttamente l'URI Web.
- DataScheme - Il filtro finalità deve dichiarare uno schema personalizzato e/o HTTPS e/o HTTPS.
- DataHost : si tratta del dominio da cui avranno origine gli URI.
- DataPathPrefix- Si tratta di un percorso facoltativo per le risorse nel sito Web, che deve iniziare con un .
/ - AutoVerify : indica ad Android di verificare la relazione tra l'app e il sito Web. Deve essere impostato su
truealtrimenti Android non verificherà l'associazione tra l'app e il sito Web e quindi non imposta l'app come gestore predefinito per un URI.
Nell'esempio seguente viene illustrato come usare per IntentFilterAttribute gestire i collegamenti da 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
{
}
Nota
È possibile specificare più schemi e host nel filtro delle finalità. Per altre informazioni, vedere Creare collegamenti diretti al contenuto dell'app in developer.android.com.
Android verificherà ogni host identificato nei filtri delle finalità rispetto al file di asset digitali nel sito Web, prima di registrare l'app come gestore predefinito per un URI. Tutti i filtri di finalità devono superare la verifica prima che Android possa stabilire l'app come gestore predefinito. Dopo aver aggiunto un filtro finalità con un URI per il contenuto dell'attività, Android è in grado di instradare qualsiasi finalità con URI corrispondenti all'app in fase di esecuzione.
Potrebbe anche essere necessario contrassegnare l'attività come esportabile, in modo che l'attività possa essere avviata da altre app. A tale scopo, è possibile aggiungere Exported = true all'oggetto esistente ActivityAttribute. Per altre informazioni, vedere Elemento Activity in developer.android.com.
Quando viene richiamata una finalità URI Web Android tenta le azioni seguenti fino a quando la richiesta non riesce:
- Apre l'app preferita per gestire l'URI.
- Apre l'unica app disponibile per gestire l'URI.
- Consente all'utente di selezionare un'app per gestire l'URI.
Per altre informazioni sulle finalità e sui filtri delle finalità, vedere Intents and intent filters on developer.android.com .For more information about intents and intent filters, see Intents and intent filters on developer.android.com.
Leggere i dati dalla finalità in ingresso
Quando Android avvia l'attività tramite un filtro finalità, è possibile usare i dati forniti dalla finalità per determinare le operazioni da eseguire. Questa operazione deve essere eseguita in un delegato del ciclo di vita iniziale, idealmente OnCreate. Il OnCreate delegato viene richiamato quando viene creata un'attività. Per altre informazioni sui delegati del ciclo di vita, vedere Eventi del ciclo di vita della piattaforma.
Per rispondere a un delegato del ciclo di vita Android richiamato, chiamare il ConfigureLifecycleEvents metodo sull'oggetto MauiAppBuilder nel CreateMauiapp metodo della MauiProgram classe. Quindi, nell'oggetto ILifecycleBuilder chiamare il AddAndroid metodo e specificare che Action registra un gestore per il delegato richiesto:
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)
{
activity.Finish();
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 proprietà recupera l'azione associata alla finalità in ingresso e la Intent.Data proprietà recupera i dati associati alla finalità in ingresso. A condizione che l'azione della finalità sia impostata su ActionView, i dati della finalità possono essere passati alla App classe con il SendOnAppLinkRequestReceived metodo .
Avviso
I collegamenti alle app offrono un potenziale vettore di attacco nell'app, quindi assicurati di convalidare tutti i parametri URI e rimuovere eventuali URI in formato non valido.
App Nella classe eseguire l'override del OnAppLinkRequestReceived metodo per ricevere ed elaborare i dati delle finalità:
namespace MyNamespace;
public partial class App : Application
{
public App()
{
InitializeComponent();
MainPage = new AppShell();
}
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());
}
}
Nell'esempio precedente, l'override OnAppLinkRequestReceived visualizza l'URI del collegamento dell'app. In pratica, il collegamento all'app deve portare gli utenti direttamente al contenuto rappresentato dall'URI, senza richieste, account di accesso o altre interruzioni. Pertanto, l'override OnAppLinkRequestReceived è la posizione da cui richiamare lo spostamento al contenuto rappresentato dall'URI.
Testare un collegamento all'app
A condizione che il file di asset digitale sia ospitato correttamente, è possibile usare Android Debug Bridge, adb, con lo strumento di gestione attività, am, per simulare l'apertura di un URI per garantire il corretto funzionamento dei collegamenti dell'app. Ad esempio, il comando seguente tenta di visualizzare un'attività dell'app di destinazione associata a un URI:
adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d YOUR_URI_HERE
Questo comando invierà una finalità che Android deve indirizzare all'app per dispositivi mobili, che deve avviare e visualizzare l'attività registrata per l'URI.
Nota
È possibile eseguire adb su un emulatore o su un dispositivo.
È anche possibile visualizzare i criteri di gestione dei collegamenti esistenti per le app installate in un dispositivo:
adb shell dumpsys package domain-preferred-apps
Questo comando visualizzerà le informazioni seguenti:
- Pacchetto: nome del pacchetto dell'app.
- Dominio: i domini, separati da spazi, i cui collegamenti Web verranno gestiti dall'app.
- Stato: stato di gestione dei collegamenti corrente per l'app. Un valore
alwaysindica che l'app è impostata suAutoVerifytruee ha superato la verifica del sistema. È seguito da un numero esadecimale che rappresenta il record della preferenza.
Per altre informazioni sul adb comando, vedere Android Debug Bridge.
Inoltre, è possibile gestire e verificare i collegamenti delle app Android tramite la console di riproduzione. Per altre informazioni, vedere Gestire e verificare i collegamenti alle app Android in developer.android.com.
Per consigli sulla risoluzione dei problemi, vedere Correggere gli errori di implementazione comuni in developer.android.com.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per