Configurare le associazioni di siti web e le regole dinamiche

Per supportare gli app link, devi creare un file JSON Digital Asset Links chiamato assetlinks.json e pubblicarlo in una posizione nota sul tuo sito web. Questo file dichiara pubblicamente quali app sono autorizzate a gestire i link per il tuo dominio e i dispositivi Android recupereranno questo file dal tuo server per verificare i tuoi link diretti.

Per gli app link dinamici in Android 15 e versioni successive, il file assetlinks.json è anche il luogo in cui definisci la configurazione delle regole dinamiche, ad esempio i pattern matcher per il percorso, il fragment e i parametri di query. I dispositivi Android con Android 15 (livello API 35) o versioni successive su cui sono installati i servizi Google recupereranno periodicamente il file e uniranno la configurazione dinamica con la configurazione statica nel file manifest dell'app.

Questa guida descrive come preparare un file assetlinks.json e pubblicarlo sul tuo sito web. Se preferisci, puoi generare un file assetlinks.json dallo strumento Play Deep Links o dall'assistente per app link di Android Studio. Per saperne di più, consulta Strumenti per sviluppatori di app link.

Dichiara le associazioni con il sito web

Devi pubblicare un file JSON Digital Asset Links sul tuo sito web per indicare le app Android associate al sito web e verificare gli intent URL dell'app. Il file JSON utilizza i seguenti campi per identificare le app associate:

package_name: l'ID applicazione dichiarato nel build.gradle file dell'app.
sha256_cert_fingerprints: le fingerprint SHA256 del certificato di firma dell'app. Puoi utilizzare il seguente comando per generare la fingerprint utilizzando Java keytool:

keytool -list -v -keystore my-release-key.keystore

Questo campo supporta più fingerprint, che possono essere utilizzate per supportare diverse versioni dell'app, ad esempio build di debug e di produzione. Se utilizzi la firma dell'app di Google Play per la tua app, la fingerprint del certificato generata eseguendo keytool in locale di solito non corrisponde a quella sui dispositivi degli utenti. Puoi verificare se utilizzi la firma dell'app di Google Play per la tua app nel tuo account sviluppatore Play Console in Release > Setup > App signing. In caso affermativo, nella stessa pagina troverai anche lo snippet JSON Digital Asset Links corretto per la tua app.

Il seguente file assetlinks.json di esempio concede i diritti di apertura dei link a un'app per Android com.example:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "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"]
  }
}]

Associa un sito web a più app

Un sito web può dichiarare associazioni con più app all'interno dello stesso file assetlinks.json. Il seguente elenco di file mostra un esempio di un file di istruzioni che dichiara l'associazione con due app, separatamente, e si trova all'indirizzo https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "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.example.monkeys.app",
    "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"]
  }
}]

App diverse possono gestire i link per risorse diverse nello stesso host web. Ad esempio, l'app1 può dichiarare un filtro per intent per https://example.com/articles e l'app2 può dichiarare un filtro per intent per https://example.com/videos.

Associa più siti web a una singola app

Più siti web possono dichiarare associazioni con la stessa app nei rispettivi file assetlinks.json. I seguenti elenchi di file mostrano un esempio di come dichiarare l'associazione di example.com ed example.net con app1. La prima scheda mostra l'associazione di example.com con app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "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"]
  }
}]

Il seguente elenco mostra l'associazione di example.net con app1. Solo la posizione in cui sono ospitati questi file è diversa (.com e .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "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"]
  }
}]

Configura le regole dinamiche

Gli app link dinamici in Android 15 e versioni successive ti consentono di utilizzare regole di corrispondenza dei link diretti lato server che funzionano insieme alle regole che hai definito staticamente nel file manifest dell'app. Il file assetlinks.json è il luogo in cui definisci le regole dinamiche. L'inclusione è facoltativa.

I dispositivi Android con Android 15 (livello API 35) o versioni successive su cui sono installati i servizi Google recupereranno periodicamente questo file dal tuo server e uniranno la configurazione delle regole dinamiche con la configurazione statica nel file manifest dell'app. Di seguito è riportato un esempio di file assetlinks.json con regole dinamiche:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Punti chiave sul codice

Gli app link dinamici aggiungono una nuova estensione di relazione Digital Asset Links chiamata dynamic_app_link_components, in cui configuri le regole dinamiche.
Le regole dinamiche possono includere pattern matcher per il percorso, il fragment e i parametri di query.
Puoi anche contrassegnare qualsiasi pattern matcher come escluso, in modo che gli URL corrispondenti non aprano la tua app.
Questo esempio mostra esempi di matcher per il percorso ("/"), il fragment ("#"), i parametri di query ("?") e i matcher esclusi ("exclude")
Se uno dei campi del file non è valido o è vuoto, Android ignora le regole dinamiche e il dispositivo torna alle regole definite staticamente nel file manifest dell'app.

Le regole dinamiche possono specificare solo le regole che si applicano all'ambito dei domini dichiarati nel file manifest dell'app. Vedi sotto.

Dichiara le regole dinamiche

Gli app link dinamici supportano una nuova estensione di relazione dynamic_app_link_components, che contiene un array di oggetti di regole. Ogni regola è definita utilizzando pattern matcher per percorsi, fragment e parametri di query che apriranno la tua app. I matcher possono anche essere esclusi singolarmente in modo che non aprano la tua app. Tutti questi sono facoltativi.

Corrispondenza percorso
- Chiave: "/"
- Valore: singola stringa, espressione di corrispondenza per il percorso dell'URL
Corrispondenza fragment
- Chiave: "#"
- Valore: singola stringa, espressione di corrispondenza per il frammento di URL
Corrispondenza parametri di query
- Chiave: "?"
- Valore: dizionario per trovare la corrispondenza delle coppie chiave-valore nei parametri di query dell'URL.
- Ad esempio, il dizionario {"?", {"dl": "*", "in_app":"true"} troverà la corrispondenza con la stringa di query "?in_app=true&dl=abc".
- L'ordine delle coppie chiave-valore nel dizionario non deve corrispondere all'ordine delle coppie nella stringa di query. Inoltre, il dizionario non deve trovare la corrispondenza di tutte le coppie chiave-valore nella stringa di query, ma deve essere trovata una corrispondenza per ogni voce del dizionario.
- Ad esempio, il dizionario troverebbe anche la corrispondenza con la stringa di query "?lang=en&in_app=true&tz=pst&dl=abc", ma non con la stringa di query "?lang=en&tz=pst&dl=abc"
Escluso
- Chiave: "exclude"
- Valore: valore true/false facoltativo per ogni regola definita in dynamic_app_link_components (vedi esempio).

Puoi utilizzare questi caratteri speciali nei pattern matcher:

"*" trova la corrispondenza di zero o più caratteri fino a quando non viene trovato il carattere dopo il carattere jolly nel pattern nella stringa corrispondente
"?" trova la corrispondenza di un singolo carattere
"?*" trova la corrispondenza di uno o più caratteri

Non esistono altre limitazioni di caratteri per i valori.

Ordina le regole dinamiche

L'ordine in cui vengono dichiarate le regole è importante. Android valuta ogni regola in ordine finché non trova una corrispondenza.

L'esempio seguente mostra in che modo l'ordinamento può influire sulla gestione. La prima regola trova la corrispondenza di tutti i percorsi ("*") ma esclude le corrispondenze (exclude: true), il che significa che esclude tutti gli URL dall'apertura dell'app. In questo caso, la seconda regola che consente "/path1" non verrà mai valutata.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

Tuttavia, nell'esempio successivo, la regola "/path1" viene dichiarata per prima, quindi verrà valutata per prima e aprirà l'app per un URL corrispondente a "/path1". La seconda regola, che esclude tutti gli URL dall'apertura dell'app, verrà valutata per seconda, ma solo se la prima regola non è una corrispondenza.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Se non vengono trovate corrispondenze nell'elenco dei componenti dichiarati, l'URL non aprirà l'app. Nell'esempio seguente, nessuno dei percorsi corrisponde a "/path3", quindi il dispositivo tratterà questo percorso come escluso.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Questo comportamento è importante se vuoi che dynamic_app_link_components escluda solo determinate parti dell'URL, ma consenta tutte le altre. Nell'esempio seguente, se ometti la regola finale per consentire tutti i percorsi rimanenti, tutti gli URL verranno esclusi dall'app.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Definisci correttamente l'ambito delle regole dinamiche

Quando definisci le regole lato server da utilizzare con gli app link dinamici in Android 15 e versioni successive, è importante definirne l'ambito in modo appropriato, in modo che funzionino con i filtri per intent statici dichiarati nel file manifest dell'app e li completino.

Le regole dinamiche dichiarate nel file assetlinks.json possono specificare solo le regole per gli host dichiarati nel file AndroidManifest.xml dell'app. Le regole dinamiche non possono espandere l'ambito delle regole URL dichiarate staticamente nel file manifest dell'app.

Per questo motivo, ti consigliamo di utilizzare questo approccio per le regole dinamiche e statiche:

Nel file manifest dell'app, imposta regole con l'ambito più ampio possibile, ad esempio dichiarando solo lo schema e il dominio.
Affidati alle regole dinamiche 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.

Dichiara dynamic_app_link_components una sola volta

Per una corretta gestione delle regole, dichiara un solo oggetto dynamic_app_link_components nelle istruzioni per un determinato sito, relazione e app.

Cerca più istruzioni per lo stesso sito, relazione e app che dichiarano un oggetto dynamic_app_link_components.
Cerca più oggetti dynamic_app_link_components dichiarati in una singola istruzione.

In questi casi, Android non garantisce quale configurazione delle regole dinamiche verrà utilizzata.

Compatibilità delle regole dinamiche con le configurazioni precedenti degli app link

Se supporti già gli app link, puoi aggiungere il supporto per gli app link dinamici direttamente nel file assetlinks.json esistente. I campi di relazione per la verifica degli app link rimangono invariati e puoi aggiungere i nuovi campi di estensione di relazione per le regole dinamiche senza apportare altre modifiche.

I dispositivi Android con Android 14 (livello API 34 o versioni precedenti) ignorano i nuovi campi di estensione di relazione per le regole dinamiche, mentre i dispositivi con Android 15 e versioni successive uniranno queste regole a quelle definite nel file manifest.

Pubblica il file JSON di verifica

Devi pubblicare il file JSON di verifica nella seguente posizione:

https://domain.name/.well-known/assetlinks.json

Assicurati di quanto segue:

Il file assetlinks.json viene pubblicato con content-type application/json.
Il file assetlinks.json deve essere accessibile tramite una connessione HTTPS, indipendentemente dal fatto che i filtri per intent dell'app dichiarino HTTPS come schema di dati.
Il file assetlinks.json deve essere accessibile senza reindirizzamenti (nessun reindirizzamento 301 o 302).
Se gli app link supportano più domini host, devi pubblicare il file assetlinks.json su ogni dominio. Consulta Supportare il collegamento di app per più host.
Non pubblicare l'app con URL di test nel file manifest che potrebbero non essere accessibili al pubblico (ad esempio quelli accessibili solo con una VPN). Una soluzione alternativa in questi casi è configurare le varianti di build per generare un file manifest diverso per le build di sviluppo.

Consulta le seguenti guide correlate: