Crea un link diretto per una destinazione

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

Il componente di 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 della tua app. Puoi mostrare un link diretto esplicito, ad esempio, all'interno di una notifica o di un widget dell'app.

Quando un utente apre la tua app tramite un link diretto esplicito, la pila di attività precedente viene cancellata e sostituita con la destinazione del link diretto. Quando nidifica i grafici, viene aggiunta allo stack anche la destinazione iniziale di ogni livello di nidificazione, ovvero la destinazione iniziale di ogni elemento <navigation> nella gerarchia. Ciò significa che quando un utente preme il pulsante Indietro da una destinazione del link diretto, torna indietro nello stack di navigazione come se avesse eseguito l'accesso alla tua app dal relativo punto di contatto.

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

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

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 lanciato predefinito Activity dichiarato nel manifest dell'app. Se NavHost si trova in un'altra attività, devi specificarne il nome del componente quando crei il generatore di link diretti:

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

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

Se hai un ComponentName, puoi passarlo direttamente al generatore:

val componentName = ...

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

ComponentName componentName = ...;

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

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

Creare un link diretto implicito

Un link diretto implicito fa riferimento 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 associati in base a URI, azioni intent e tipi MIME. Puoi specificare più tipi di corrispondenza per un singolo link diretti, ma tieni presente che la corrispondenza degli argomenti URI ha la priorità, seguita dall'azione e dal tipo MIME.

Ecco un esempio di link diretto 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 Editor di navigazione per creare un link diretto implicito a una destinazione come segue:

1. Nella scheda Design dell'editor di navigazione, seleziona la destinazione per il 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 schema sono considerati come http o https. Ad esempio, www.google.com corrisponde sia a http://www.google.com sia a https://www.google.com.
   • I segnaposto dei parametri di percorso sotto forma di {placeholder_name} corrispondono a uno o più caratteri. Ad esempio, http://www.example.com/users/{id} corrisponde http://www.example.com/users/4. Il componente di navigazione tenta di analizzare i valori dei segnaposto in tipi appropriati associando i nomi dei segnaposto agli argomenti definiti per la destinazione del link diretto. Se non è definito alcun argomento con lo stesso nome, per il valore dell'argomento viene utilizzato un tipo String predefinito. Puoi utilizzare il carattere jolly .* per trovare una corrispondenza con nessuno o più caratteri.
   • I segnaposto dei parametri di query possono essere utilizzati al posto o in combinazione con i parametri di percorso. Ad esempio, http://www.example.com/users/{id}?myarg={myarg} corrisponde a http://www.example.com/users/4?myarg=28.
   • I segnaposto dei parametri di query per le variabili definite con valori predefiniti o obbligatori non devono corrispondere. 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. Non è così per i parametri del percorso. Ad esempio, http://www.example.com/users?arg1=7&arg2=28 non corrisponde al pattern riportato sopra perché il parametro path richiesto non è fornito.
   • I parametri di query estranei 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 tu sia il proprietario dell'URI. Per ulteriori informazioni, consulta Verificare Android App Links.

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

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

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

Per attivare i link diretti impliciti, devi anche apportare aggiunte al file manifest.xml della tua app. Aggiungi un singolo elemento <nav-graph> a un'attività che fa riferimento a un grafo 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 di navigazione sostituisce l'elemento <nav-graph> con elementi <intent-filter> generati in modo che corrispondano a tutti i link diretti nel grafo di navigazione.

Quando viene attivato un link diretto implicito, lo stato della pila di ritorno dipende dal fatto che Intent implicito sia stato avviato con il flag Intent.FLAG_ACTIVITY_NEW_TASK:

• Se il flag è impostato, la pila di attività precedenti viene cancellata e sostituita con la destinazione del link diretto. Come per i link diretti espliciti, quando nidifica i grafici, viene aggiunta allo stack anche la destinazione iniziale di ogni livello di nidificazione, ovvero la destinazione iniziale di ogni elemento <navigation> nella gerarchia. Ciò significa che quando un utente preme il pulsante Indietro da una destinazione del link diretto, torna indietro nello stack di navigazione come se avesse aperto la tua app dal punto di contatto.
• Se il flag non è impostato, rimani nello stack di attività dell'app precedente dove è 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

È vivamente consigliato di utilizzare sempre il valore predefinito launchMode di standard quando utilizzi la navigazione. Quando utilizzi la modalità di lancio standard, Navigazione gestisce automaticamente i link diretti chiamando handleDeepLink() per elaborare eventuali link diretti espliciti o impliciti all'interno del Intent. Tuttavia, questo non avviene automaticamente se il 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:

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

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

Risorse aggiuntive

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

Codelab

• Codelab sulla navigazione

Video

• Android Jetpack: gestire la navigazione nell'interfaccia utente con Navigation Controller (Google I/O '18)