Aggiungere filtri per intent per i link per app

Gli app link sono deep link che utilizzano lo schema HTTP o HTTPS, la cui associazione al tuo sito web è verificata da Android. Per registrarti e gestire gli app link, segui questi passaggi:

Aggiungi uno o più filtri per intent al file manifest dell'app che specificano il dominio o gli URL del tuo sito web.
Aggiungi autoVerify="true"attribute agli elementi del filtro per intent. Questo indica al sistema che deve tentare di verificare lo schema e i domini host in base alla configurazione assetlinks.json del tuo sito web.
Dichiara le associazioni con il sito web.

Di seguito è riportato un esempio di dichiarazione di app link con schemi e host, nonché autoVerify="true":

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

Punti chiave sul codice

Verifica automatica: l'attributo android:autoVerify="true" è obbligatorio per gli app link. Indica al sistema che deve tentare di verificare l' associazione tra la tua app e gli schemi e i domini specificati nei <data> tag. Ti consigliamo di aggiungere autoVerify="true" a ogni filtro per intent che vuoi che sia verificabile.
Elementi di dati: ogni filtro per intent degli app link deve includere uno o più elementi <data> che specificano gli schemi e i formati host corrispondenti al dominio verificabile del tuo sito web.
Schemi: il filtro per intent deve includere elementi <data> sia per gli schemi http che https.
Host: se vuoi, puoi aggiungere elementi <data> che corrispondano a uno o più host. Utilizza un carattere jolly (*) per creare una corrispondenza con più sottodomini (ad esempio *.example.com). Il sistema tenterà di verificare ogni host in base al file assetlinks.json sul tuo sito web. Tieni presente che qualsiasi routing a livello di percorso deve essere gestito dal file assetlinks.json (vedi la sezione delle best practice di seguito).
Più host: se dichiari più domini host, il sistema (su Android 12 e versioni successive) tenta di verificarli tutti. Se un host viene verificato, l'app diventa il gestore predefinito per i link provenienti da quell'host verificato. Su Android 11 e versioni precedenti, la verifica non riesce se anche un solo host non può essere verificato.
Più filtri per intent: è importante creare filtri separati quando l'intenzione è dichiarare URL unici (ad esempio una combinazione specifica di schema e host), perché più elementi <data> nello stesso filtro per intent vengono uniti per rappresentare tutte le varianti dei loro attributi combinati.

Considerazioni sulle regole dei filtri per il file manifest

Se stai configurando filtri da utilizzare con app link dinamici in Android 15 o versioni successive, è importante ricordare che le regole dinamiche dichiarate nel file assetlinks.json lato server non possono espandere l'ambito delle regole URL dichiarate staticamente nel file manifest dell'app.

Per questo motivo, ti consigliamo di utilizzare questo approccio:

Nel file manifest dell'app, imposta l'ambito più ampio possibile, ad esempio dichiarando solo lo schema e il dominio.
Affidati alle regole nel file assetlinks.json lato server per un ulteriore perfezionamento, ad esempio il routing a livello di percorso.

Con questa configurazione ideale, potrai aggiungere dinamicamente nuovi percorsi di app link nel file assetlinks.json in base alle esigenze, sapendo che rientreranno nell'ambito ampio che hai impostato nel file manifest dell'app.

Supportare gli app link per più host

Il sistema deve essere in grado di verificare l'host specificato negli elementi di dati dei filtri per intent degli URL dell'app rispetto ai file Digital Asset Links ospitati sui rispettivi domini web nel filtro per intent specifico. Se la verifica non va a buon fine, il sistema applica il suo comportamento standard predefinito per risolvere l'intent, come descritto in Creare deep link ai contenuti dell'app. Tuttavia, l'app può comunque essere verificata come gestore predefinito per qualsiasi pattern URL definito negli altri filtri per intent dell'app.

Ad esempio, un'app con i seguenti filtri per intent supererebbe la verifica solo per https://www.example.com se venisse trovato un file assetlinks.json in https://www.example.com/.well-known/assetlinks.json ma non in https://www.example.net/.well-known/assetlinks.json:

<application>

  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

Supportare gli app link per più sottodomini

Il protocollo Digital Asset Links considera i sottodomini nei filtri per intent come host unici e separati. Pertanto, se il filtro per intent elenca più host con sottodomini diversi, devi pubblicare un file assetlinks.json valido su ogni dominio. Ad esempio, il seguente filtro di intent include www.example.com e mobile.example.com come host URL di intent accettati. Pertanto, un file assetlinks.json valido deve essere pubblicato sia su https://www.example.com/.well-known/assetlinks.json sia su https://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

In alternativa, se dichiari il nome host con un carattere jolly (ad esempio *.example.com), devi pubblicare il file assetlinks.json nel nome host principale (example.com). Ad esempio, un'app con il seguente filtro per intent supererà la verifica per qualsiasi nome secondario di example.com (ad esempio foo.example.com) a condizione che il file assetlinks.json sia pubblicato all'indirizzo https://example.com/.well-known/assetlinks.json:

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Verificare la presenza di più app associate allo stesso dominio

Se pubblichi più app associate allo stesso dominio, ognuna può essere verificata correttamente. Tuttavia, se le app possono risolvere lo stesso identico host e lo stesso identico percorso di dominio, come nel caso delle versioni Lite e complete di un'app, solo l'app installata più di recente può risolvere gli intent web per quel dominio.

In un caso come questo, verifica la presenza di possibili app in conflitto sul dispositivo dell'utente, a condizione che tu disponga della visibilità del pacchetto necessaria. Poi, nella tua app, mostra una finestra di dialogo personalizzata per la selezione che contiene i risultati della chiamata a queryIntentActivities. L'utente può selezionare l'app che preferisce dall'elenco delle app corrispondenti visualizzate nella finestra di dialogo.

Compatibilità con le versioni precedenti degli app link dinamici per Android 14 e versioni precedenti

Le funzionalità degli app link dinamici, incluse le regole di corrispondenza avanzate in assetlinks.json e l'utilizzo di <uri-relative-filter-group>, sono completamente supportate solo su Android 15 (livello API 35) e versioni successive.

Su Android 14 (livello API 34) e versioni precedenti, il sistema considera solo i scheme e host dichiarati negli elementi <data> del file manifest per la verifica degli app link. Le regole, le esclusioni e gli aggiornamenti dinamici specifici per il percorso di assetlinks.json non vengono applicati.

Ciò significa che se il file manifest specifica solo scheme e host, l'app potrebbe acquisire in modo imprevisto tutti i percorsi per il dominio verificato su Android 14 e versioni precedenti, indipendentemente dalle regole specifiche per il percorso definite in assetlinks.json per Android 15 e versioni successive.

Strategia di fallback per le versioni precedenti di Android da configurare senza deep link

Per impedire alla tua app di gestire tutti i link per un dominio su Android 14 e versioni precedenti quando intendi utilizzare gli app link dinamici per percorsi più specifici su Android 15 e versioni successive, includi un percorso non corrispondente nel filtro per intent del file manifest. Aggiungi un elemento <data> con un attributo android:path che difficilmente sarà un percorso valido per i tuoi link. In questo modo, il filtro per intent non corrisponde a tutti i percorsi nelle versioni precedenti.

Esempio:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

Aggiungendo <data android:path="/no_match_for_older_android_versions" />, ti assicuri che su Android 14 e versioni precedenti questo filtro per intent non corrisponda a nessun link in entrata, consentendo comunque di verificare il dominio per l'utilizzo con gli app link dinamici su Android 15 e versioni successive in base alle regole di corrispondenza avanzate nelle regole assetlinks.json

Migrazione degli app link esistenti

Se hai già app link con regole di percorso specifiche (ad esempio android:pathPrefix) nel file manifest e vuoi iniziare a utilizzare gli app link dinamici su Android 15 e versioni successive, puoi aggiungere in sicurezza l'elemento <uri-relative-filter-group> direttamente ai filtri per intent esistenti.

Poiché Android 14 e versioni precedenti ignorano l'elemento <uri-relative-filter-group>, gli app link esistenti continuano a funzionare esattamente come ora sui dispositivi con versioni precedenti di Android.

Tuttavia, devi valutare attentamente in che modo Android 15 e versioni successive valutano la configurazione "mista":

Filtro a due livelli:su Android 15 e versioni successive, il sistema valuta i filtri per intent come unione. Un URL supera il controllo del file manifest se soddisfa i tag statici precedenti <data> o le regole generali in <uri-relative-filter-group>. Una volta che l'URL supera questo controllo iniziale del file manifest, il sistema applica le regole dinamiche definite nel file assetlinks.json come secondo livello di filtro granulare. Ciò significa che le regole JSON lato server determinano in definitiva quali di questi URL corrispondenti aprono effettivamente l'app.

Esempio di configurazione ibrida :

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>