Creare link diretti

Il deep linking ti consente di indirizzare gli utenti direttamente alla tua app da browser web, notifiche, social media, annunci e altre fonti. I deep link forniscono transizioni dirette da app ad app e da web ad app che possono aiutarti ad aumentare il coinvolgimento tramite contenuti contestuali e mirati.

Questa guida spiega come funziona il deep linking e come creare e testare i deep link ai tuoi contenuti.

Per i deep link che fanno riferimento al tuo sito web o ai tuoi domini, ti consigliamo di utilizzare App Links, che offre un'esperienza fluida e affidabile per gli utenti.

Come funziona il deep linking

Il deep linking è una funzionalità di sistema generale di Android, supportata su tutte le versioni e su tutti i dispositivi. Sfrutta il sistema di intent di Android per indirizzare i deep link alle app interessate. Le app che vogliono gestire un URI di deep link specifico dichiarano un filtro per intent corrispondente nei file manifest dell'app.

In fase di runtime, quando l'utente tocca un link, Android attiva un intent e tenta di indirizzarlo a un'app. Poiché più app possono dichiarare filtri per intent che corrispondono a un determinato URI, Android esegue queste azioni, in questo ordine, per indirizzare l'intent:

1. Aprire l'app predefinita dell'utente in grado di gestire l'URI, se ne è stata designata una.
2. Apri l'unica app disponibile in grado di gestire l'URI.
3. Consenti all'utente di selezionare un'app da una finestra di dialogo di disambiguazione.

Ciò significa che, anche se i filtri per intent corrispondono a un determinato URI, non è garantito che il sistema indirizzi l'intent del deep link alla tua app. L'utente svolge un ruolo chiave nella gestione dell'app che gestisce l'intent, il che gli offre controllo e scelta. Per un maggiore controllo sui deep link al tuo sito web e ai tuoi domini, prova a utilizzare App Links.

La finestra di dialogo di disambiguazione di Android consente all'utente di visualizzare tutte le app installate che sono state registrate per gestire un intent di deep link. L'utente può anche selezionare un'app come predefinita per questo tipo di link. Una volta che l'utente imposta un'app predefinita, il sistema non mostra più la finestra di dialogo per quell'intent specifico e l'app scelta si apre automaticamente.

Figura 1. La finestra di dialogo di disambiguazione

Il comportamento della finestra di dialogo di disambiguazione si è evoluto nelle varie versioni di Android. Ad esempio, su Android 12 e versioni successive, i link web che non sono app link verificati vengono generalmente aperti in un browser web per impostazione predefinita, mentre nelle versioni precedenti potrebbe essere visualizzata una finestra di dialogo di disambiguazione se un'app poteva gestire il link web.

Nota: a partire da Android 12 (livello API 31), un intent web generico viene risolto in un'attività nella tua app solo se quest'ultima è approvata per il dominio specifico contenuto nell'intent web. Se la tua app non è approvata per il dominio, l'intent web viene risolto nell'app browser predefinita dell'utente.

Tipi di deep link

Esistono tre tipi di deep link che puoi supportare su Android:

• Deep link personalizzati: si tratta di deep link che utilizzano uno schema URI personalizzato (ad esempio example://products/123) per indirizzare un utente direttamente a un contenuto specifico all'interno di un'app. Sono utili per la navigazione interna o per i link provenienti da fonti che controlli, ma non sono link web standard e possono comunque attivare la finestra di dialogo di disambiguazione se un'altra app registra lo stesso schema personalizzato.
• Link web: si tratta di deep link che utilizzano gli schemi standard http e https. Sono più versatili perché sono URL standard, ma su Android 12 e versioni successive attiveranno quasi sempre la finestra di dialogo di disambiguazione, il che significa che è probabile che vengano gestiti dal browser web dell'utente per impostazione predefinita, anziché essere indirizzati alla tua app.
• Link alle app: disponibili a partire da Android 6.0 (livello API 23), sono link web verificati. Tramite un processo di associazione del sito web, puoi dimostrare al sistema Android di essere il proprietario del dominio. Una volta eseguita la verifica, il sistema indirizza automaticamente i link di quel dominio direttamente alla tua app, saltando completamente la finestra di dialogo di disambiguazione. In questo modo, gli utenti possono usufruire di un'esperienza affidabile e fluida.

Aggiungi filtri per intent per i link in entrata

Per creare un link ai contenuti della tua app, aggiungi un filtro per intent che contenga questi elementi e valori degli attributi nel manifest:

<action>

Specifica l'azione intent ACTION_VIEW in modo che il filtro per intent possa essere raggiunto dalla Ricerca Google.

<data>

Aggiungi uno o più tag <data>, ognuno dei quali rappresenta un formato URI che si risolve nell'attività. Come minimo, il tag <data> deve includere l'attributo android:scheme.

Puoi aggiungere altri attributi per perfezionare ulteriormente il tipo di URI accettato dall'attività. Ad esempio, potresti avere più attività che accettano URI simili, ma che differiscono in base al percorso. In questo caso, utilizza l'attributo android:path o le relative varianti pathPattern o pathPrefix per differenziare l'attività che il sistema deve aprire per i diversi percorsi URI.

<category>

Includi la categoria BROWSABLE. È necessario affinché il filtro per intent sia accessibile da un browser web. Senza questo file, un clic su un link in un browser non può indirizzare alla tua app.

Includi anche la categoria DEFAULT. In questo modo, l'app può rispondere agli intent impliciti. Senza questo attributo, l'attività può essere avviata solo se l'intent specifica il nome del componente dell'app.

Il seguente snippet XML mostra come specificare un filtro per intent nel manifest per il deep linking. Gli URI "example://gizmos" e "http://www.example.com/gizmos" rimandano entrambi a questa attività.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos" -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos" -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

Tieni presente che i due filtri per intent differiscono solo per l'elemento <data>. Sebbene sia possibile includere più elementi <data> nello stesso filtro, è importante creare filtri separati quando l'intenzione è dichiarare URL univoci (ad esempio una combinazione specifica di scheme e host), perché più elementi <data> nello stesso filtro per intent vengono effettivamente uniti per rappresentare tutte le varianti dei loro attributi combinati. Ad esempio, considera quanto segue:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

Potrebbe sembrare che supporti solo https://www.example.com e app://open.my.app. Tuttavia, in realtà supporta questi due, oltre a: app://www.example.com e https://open.my.app.

Attenzione: se più attività contengono filtri per intent che si riferiscono allo stesso app link Android verificato, non c'è alcuna garanzia di quale attività gestirà il link.

Dopo aver aggiunto al manifest dell'app i filtri per intent con gli URI per i contenuti delle attività, Android è in grado di indirizzare all'app in fase di runtime qualsiasi Intent con URI corrispondenti.

Per scoprire di più sulla definizione dei filtri per intent, consulta Consentire ad altre app di avviare la tua attività.

Leggi i dati dagli intent in entrata

Una volta che il sistema avvia la tua attività tramite un filtro per intent, puoi utilizzare i dati forniti da Intent per determinare cosa devi visualizzare. Chiama i metodi getData() e getAction() per recuperare i dati e l'azione associati all'oggetto Intent in entrata. Puoi chiamare questi metodi in qualsiasi momento durante il ciclo di vita dell'attività, ma in genere dovresti farlo durante i primi callback, come onCreate() o onStart.

Ecco uno snippet che mostra come recuperare i dati da un Intent:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

Segui queste best practice per migliorare l'esperienza utente:

• Il deep link deve indirizzare gli utenti direttamente ai contenuti, senza prompt, pagine interstitial o accessi. Assicurati che gli utenti possano visualizzare i contenuti dell'app anche se non l'hanno mai aperta in precedenza. È consentito chiedere agli utenti di eseguire l'accesso durante le interazioni successive o quando aprono l'app da Avvio app.
• Segui le indicazioni di progettazione descritte in Navigazione con Indietro e Su in modo che la tua app corrisponda alle aspettative degli utenti per la navigazione a ritroso dopo che accedono alla tua app tramite un deep link.

Verifica dei link diretti

Puoi utilizzare Android Debug Bridge con lo strumento Activity Manager (am) per verificare che gli URI dei filtri per intent specificati per il deep linking vengano risolti nell'attività corretta dell'app. Puoi eseguire il comando adb su un dispositivo o un emulatore.

La sintassi generale per testare un URI del filtro per intent con adb è:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

Ad esempio, il seguente comando tenta di visualizzare un'attività dell'app di destinazione associata all'URI specificato.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

Nota :quando definisci una raccolta di tipi primitivi in un percorso, ad esempio @Serializable data class Product(val colors: List), il formato dell'URL del deep link generato automaticamente è basePath?colors={value}. Se provi a specificare un URI con più parametri di query (ad esempio, basepath?colors=red&colors=blue), devi utilizzare il carattere di escape per la e commerciale (ad esempio, basepath?colors=red\&colors=blue).

A partire da Android 17, puoi anche utilizzare il flag --debug-link con am start per diagnosticare il modo in cui il sistema risolve un URL e ispezionare i filtri per intent corrispondenti o le regole dei link alle app dinamici. Per saperne di più, consulta Diagnostica la risoluzione dei link con il flag debug-link.

La dichiarazione del file manifest e il gestore di intent che imposti definiscono la connessione tra la tua app e un sito web e cosa fare con i link in entrata. Tuttavia, per fare in modo che il sistema tratti la tua app come gestore predefinito per un insieme di URI, devi anche richiedere al sistema di verificare questa connessione. L'articolo Verifica gli app link spiega come implementare questa verifica.

Per scoprire di più sugli intent e sui link alle app, consulta le seguenti risorse:

• Intent e filtri per intent
• Consenti ad altre app di avviare la tua attività
• Aggiungi Android App Links con Android Studio