Crea un link diretto per una destinazione

In Android, un link diretto è un link che porta direttamente a una destinazione specifica all'interno di un'app.

Il componente Navigazione consente di creare due diversi tipi di link diretti: espliciti e impliciti.

Creare un link diretto esplicito

Un link diretto esplicito è una singola istanza di un link diretto che utilizza un PendingIntent per indirizzare gli utenti a una posizione specifica all'interno dell'app. Ad esempio, puoi mostrare un link diretto esplicito all'interno di una notifica o di un widget dell'app.

Quando un utente apre la tua app tramite un link diretto esplicito, lo stack di back dell'attività viene cancellato e sostituito con la destinazione del link diretto. Durante la nidificazione dei grafici, allo stack viene aggiunta anche la destinazione iniziale di ogni livello di nidificazione, ovvero la destinazione iniziale di ogni elemento <navigation> della gerarchia. Ciò significa che, quando un utente preme il pulsante Indietro dalla destinazione di un link diretto, torna indietro nello stack di navigazione proprio come se fosse entrato nell'app dal punto di accesso.

Puoi utilizzare la classe NavDeepLinkBuilder per creare una PendingIntent, come mostrato nell'esempio seguente. Tieni presente che se il contesto fornito non è Activity, il costruttore utilizza PackageManager.getLaunchIntentForPackage() come attività predefinita da avviare, se disponibile.

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

Per impostazione predefinita, NavDeepLinkBuilder avvia il link diretto esplicito nel lancio predefinito Activity dichiarato nel file manifest dell'app. Se NavHost si trova in un'altra attività, devi specificare il nome del componente durante la creazione dello strumento per la creazione di link diretti:

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

Se hai una ComponentName, puoi passarla direttamente allo strumento per la creazione:

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

Se hai già una NavController, puoi anche creare un link diretto utilizzando NavController.createDeepLink().

Attenzione: questa API consente di creare link diretti a qualsiasi schermata dell'app, anche se quella schermata non supporta i link diretti impliciti. Segui la pagina Navigazione condizionale per assicurarti che le schermate che richiedono l'accesso reindirizzino gli utenti a queste schermate quando la raggiungi tramite un link diretto.

Creare un link diretto implicito

Un link diretto implicito si riferisce a una destinazione specifica in un'app. Quando il link diretto viene richiamato, ad esempio quando un utente fa clic su un link, Android può aprire la tua app nella destinazione corrispondente.

I link diretti possono essere abbinati per URI, azioni intent e tipi MIME. Puoi specificare più tipi di corrispondenza per un singolo link diretto, ma tieni presente che la corrispondenza dell'argomento URI ha la priorità, seguita dall'azione e poi dal tipo MIME.

Di seguito è riportato un link diretto di esempio che contiene un URI, un'azione e un tipo MIME:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

Puoi anche utilizzare l'editor di navigazione per creare un link diretto implicito a una destinazione, come indicato di seguito:

1. Nella scheda Design dell'editor di navigazione, seleziona la destinazione del link diretto.
2. Fai clic su + nella sezione Link diretti del riquadro Attributi.

3. Nella finestra di dialogo Aggiungi link diretto visualizzata, inserisci le informazioni per il link diretto.

   Nota:

   • Gli URI senza uno schema vengono presi come http o https. Ad esempio, www.google.com corrisponde sia a http://www.google.com che a https://www.google.com.
   • I segnaposto dei parametri del percorso sotto forma di {placeholder_name} corrispondono a uno o più caratteri. Ad esempio, http://www.example.com/users/{id} corrisponde a http://www.example.com/users/4. Il componente Navigazione tenta di analizzare i valori segnaposto in tipi appropriati abbinando i nomi dei segnaposto agli argomenti definiti per la destinazione del link diretto. Se non viene definito alcun argomento con lo stesso nome, viene utilizzato un tipo predefinito di String come valore dell'argomento. Puoi utilizzare il carattere jolly .* per trovare una corrispondenza con zero o più caratteri.
   • I segnaposto dei parametri di query possono essere utilizzati al posto dei parametri del percorso o insieme ad essi. Ad esempio, http://www.example.com/users/{id}?myarg={myarg} corrisponde a http://www.example.com/users/4?myarg=28.
   • Non è necessario abbinare i segnaposto dei parametri di query per le variabili definite con valori predefiniti o nulli. Ad esempio, http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} corrisponde a http://www.example.com/users/4?arg2=28 o http://www.example.com/users/4?arg1=7. Questo non avviene con i parametri percorso. Ad esempio, http://www.example.com/users?arg1=7&arg2=28 non corrisponde al pattern riportato sopra perché il parametro del percorso richiesto non viene fornito.
   • I parametri di query non pertinenti non influiscono sulla corrispondenza dell'URI del link diretto. Ad esempio, http://www.example.com/users/{id} corrisponde a http://www.example.com/users/4?extraneousParam=7, anche se extraneousParam non è definito nel pattern URI.

4. (Facoltativo) Seleziona Verifica automatica per richiedere a Google di verificare che l'URI sia di tua proprietà. Per ulteriori informazioni, consulta la sezione Verificare i link per le app Android.

5. Fai clic su Aggiungi. Sopra la destinazione selezionata viene visualizzata un'icona del link per indicare che la destinazione ha un link diretto.

6. Fai clic sulla scheda Codice per passare alla visualizzazione XML. Un elemento <deepLink> nidificato è stato aggiunto alla destinazione:

   <deepLink app:uri="https://www.google.com" />
   

Per attivare i link diretti impliciti, devi anche aggiungere elementi al file manifest.xml della tua app. Aggiungi un singolo elemento <nav-graph> a un'attività che rimanda a un grafico di navigazione esistente, come mostrato nell'esempio seguente:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

Durante la creazione del progetto, il componente Navigazione sostituisce l'elemento <nav-graph> con gli elementi <intent-filter> generati per corrispondere a tutti i link diretti nel grafico di navigazione.

Quando si attiva un link diretto implicito, lo stato dello stack di back-forward dipende dal fatto che il valore Intent implicito sia stato avviato con il flag Intent.FLAG_ACTIVITY_NEW_TASK:

• Se il flag è impostato, lo stack di back dell'attività viene cancellato e sostituito con la destinazione del link diretto. Come nel caso dei link diretti espliciti, durante la nidificazione dei grafici viene aggiunta allo stack anche la destinazione iniziale di ogni livello di nidificazione, ovvero la destinazione iniziale di ogni elemento <navigation> della gerarchia. Ciò significa che, quando un utente preme il pulsante Indietro dalla destinazione di un link diretto, torna indietro nello stack di navigazione come se fosse entrato nell'app dal punto di ingresso.
• Se il flag non è impostato, rimani nello stack di attività dell'app precedente in cui è stato attivato il link diretto implicito. In questo caso, il pulsante Indietro ti riporta all'app precedente, mentre il pulsante Su avvia l'attività dell'app nella destinazione principale gerarchica all'interno del grafico di navigazione.

Gestione dei link diretti

Ti consigliamo vivamente di utilizzare sempre il valore predefinito launchMode di standard quando utilizzi la navigazione. Quando utilizzi la modalità di avvio di standard, la navigazione gestisce automaticamente i link diretti chiamando handleDeepLink() per elaborare eventuali link diretti espliciti o impliciti all'interno di Intent. Tuttavia, ciò non avviene automaticamente se Activity viene riutilizzato quando si utilizza un launchMode alternativo come singleTop. In questo caso, è necessario chiamare manualmente handleDeepLink() in onNewIntent(), come mostrato nell'esempio seguente:

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

Risorse aggiuntive

Per scoprire di più sulla navigazione, consulta le risorse seguenti.

Samples

• Esempio di base di navigazione nei componenti dell'architettura Android

Codelab

• Codelab sulla navigazione

Video

• Android Jetpack: gestire la navigazione nell'interfaccia utente con il controller di navigazione (Google I/O '18)