Configurare le associazioni di siti web e le regole dinamiche

Per supportare i link per app, devi creare un file JSON Digital Asset Links denominato 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 lo recuperano dal tuo server per verificare i tuoi deep link.

Per gli app link dinamici in Android 15 e versioni successive, il file assetlinks.json è anche il luogo in cui definire la configurazione delle regole dinamiche, ad esempio i pattern matcher per percorso, frammento e 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 quella statica nel 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 link per app.

Dichiarare le associazioni di siti web

Devi pubblicare un file JSON Digital Asset Links sul tuo sito web per indicare le app per 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 file build.gradle dell'app.
  • sha256_cert_fingerprints: le impronte SHA256 del certificato di firma della tua app. Puoi utilizzare il seguente comando per generare l'impronta utilizzando Java Keytool:

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

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

Il seguente esempio di file assetlinks.json concede i diritti di apertura dei link a un'app 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"]
  }
}]

Associare 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 file dichiarazione che dichiara l'associazione a due app, separatamente, e si trova in 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 potrebbero 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, mentre l'app2 può dichiarare un filtro per intent per https://example.com/videos.

Associare 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 ad 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"]
  }
}]

La seguente scheda mostra l'associazione di example.net ad 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"]
  }
}]

Configurare le regole dinamiche

I link dinamici per app 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 della tua app. Il file assetlinks.json è il punto in cui definisci le regole dinamiche. Questa opzione è 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 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 del codice

  • Gli app link dinamici aggiungono una nuova estensione di relazione Digital Asset Links chiamata dynamic_app_link_components, in cui configurare le regole dinamiche.
  • Le regole dinamiche possono includere pattern matcher per percorso, frammento e 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 percorso ("/"), frammento ("#") e parametri di query ("?"), nonché matcher esclusi ("exclude")
  • Se uno dei campi del file non è valido o è vuoto, Android ignora le regole dinamiche e il dispositivo utilizza le regole definite staticamente nel manifest dell'app.

Le regole dinamiche possono specificare solo regole che si applicano nell'ambito dei domini che dichiari nel file manifest della tua app. Continua a leggere per ulteriori informazioni.

Dichiarare le regole dinamiche

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

  • Corrispondenza percorso
    • Chiave: "/"
    • Valore: singola stringa, espressione di corrispondenza per il percorso dell'URL
  • Corrispondenza dei frammenti
    • Chiave: "#"
    • Valore: stringa singola, espressione di corrispondenza per il frammento di URL
  • Corrispondenza parametri di query
    • Chiave: "?"
    • Valore: dizionario per trovare corrispondenze tra le coppie chiave/valore nei parametri di query dell'URL.
    • Ad esempio, il dizionario {"?", {"dl": "*", "in_app":"true"} corrisponderà alla 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 corrispondere a 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 corrispondenza anche 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 vero/falso facoltativo per ogni regola definita in dynamic_app_link_components (vedi esempio).

Puoi utilizzare questi caratteri speciali nei pattern matcher:

  • "*" trova corrispondenze con zero o più caratteri fino a quando non viene trovato il carattere dopo il carattere jolly nella stringa corrispondente
  • "?" corrisponde a qualsiasi singolo carattere
  • "?*" corrisponde a uno o più caratteri

Non sono previste altre limitazioni di caratteri per i valori.

Ordinare le regole dinamiche

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

Il seguente esempio mostra come l'ordinamento può influire sulla gestione. La prima regola corrisponde a tutti i percorsi ("*"), ma esclude le corrispondenze (exclude: true), il che significa che esclude l'apertura dell'app da tutti gli URL. 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 l'apertura dell'app da tutti gli URL, verrà valutata per seconda, ma solo se la prima regola non corrisponde.

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

Definisci correttamente l'ambito delle regole dinamiche

Quando definisci le regole lato server da utilizzare con i link dinamici per app 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 manifest dell'app e li completino.

Le regole dinamiche dichiarate nel file assetlinks.json possono specificare solo regole per gli host dichiarati nel file AndroidManifest.xml della tua app. Le regole dinamiche non possono espandere l'ambito delle regole URL che dichiari staticamente nel 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 link app nel file assetlinks.json in base alle esigenze, sapendo che rientreranno nell'ambito ampio che hai impostato nel manifest dell'app.

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 un'unica 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 già supporti i link per app, puoi aggiungere il supporto dei link per app dinamici direttamente nel file assetlinks.json esistente. I campi di relazione per la verifica dei link dell'app rimangono invariati e puoi aggiungere i nuovi campi di estensione della relazione per le regole dinamiche senza altre modifiche.

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

Pubblicare il file JSON di verifica

Devi pubblicare il file di verifica JSON 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 i link della tua app supportano più domini host, devi pubblicare il file assetlinks.json su ogni dominio. Consulta Supporto del collegamento di app per più host.
  • Non pubblicare la tua app con URL di test nel file manifest che potrebbero non essere accessibili al pubblico (ad esempio quelli accessibili solo con una VPN). In questi casi, una soluzione alternativa consiste nel configurare le varianti di build per generare un file manifest diverso per le build di sviluppo.

Consulta le seguenti guide correlate: