Sintassi dell'elenco di istruzioni

Un elenco di dichiarazioni è un file o uno snippet codificato in JSON in una posizione nota.

Posizione dell'elenco degli estratti conto

Consulta l'articolo Creare un elenco di dichiarazioni per scoprire dove deve essere archiviato questo elenco.

Sintassi

L'elenco o lo snippet di istruzioni è costituito da un array JSON di una o più istruzioni di siti web o app come oggetti JSON. Queste istruzioni possono essere in qualsiasi ordine. Ecco la sintassi generale:

[
  {
    "relation": ["relation_string"],
    "target": {target_object}
  } , ...
]

relation

Un array di una o più stringhe che descrivono la relazione dichiarata in merito alla destinazione. Consulta l'elenco delle stringhe di relazione definite. Esempio: delegate_permission/common.handle_all_urls

target

L'asset di destinazione a cui si applica questa dichiarazione. Tipi di target disponibili:

• Destinazione sito web

  "target": {
    "namespace": "web",
    "site": "site_root_url"
  }

  spazio dei nomi

  Deve essere web per i siti web.

  sito

  URI del sito di destinazione dell'istruzione, nel formato http[s]://<hostname>[:<port>], dove <hostname> è completo e <port> deve essere omesso quando si utilizza la porta 80 per HTTP o la porta 443 per HTTPS. Un target del sito web può essere solo un dominio principale; non puoi limitarlo a una sottodirectory specifica; tutte le directory sotto questa radice corrisponderanno. I sottodomini non devono essere considerati corrispondenti: ovvero, se il file delle dichiarazioni è ospitato su www.example.com, www.puppies.example.com non deve essere considerato una corrispondenza. Per regole ed esempi sulla corrispondenza dei target dei siti web, consulta la documentazione sui target. Esempio: http://www.example.com

• Target dell'app per Android

  "target": {
    "namespace": "android_app",
    "package_name": "fully_qualified_package_name",
    "sha256_cert_fingerprints": ["cert_fingerprint"]
  }

  spazio dei nomi

  Deve essere android_app per le app per Android.

  package_name

  Il nome del pacchetto completo dell'app a cui si applica questa dichiarazione. Esempio: com.google.android.apps.maps

  sha256_cert_fingerprints

  L'impronta SHA256 in maiuscolo del certificato dell'app a cui si applica questa dichiarazione. Puoi calcolarlo utilizzando openssl o Java keytool come mostrato qui:

  • openssl x509 -in $CERTFILE -noout -fingerprint -sha256
  • keytool -printcert -file $CERTFILE | grep SHA256

  Esempio: ["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"].

  Se utilizzi la firma dell'app di Google Play per la tua app, la fingerprint del certificato generata eseguendo keytool o openssl localmente di solito non corrisponde a quella sui dispositivi degli utenti. Puoi verificare se utilizzi la firma delle app di Google Play per la tua app nel tuo account sviluppatore Play Console nella sezione Release > Setup > App Integrity; in caso affermativo, nella stessa pagina troverai anche lo snippet JSON Digital Asset Links corretto per la tua app.

relation_extensions (facoltativo)

Puoi aggiungere un campo relation_extensions facoltativo a un'affermazione per fornire maggiori informazioni sulle autorizzazioni e sulle associazioni che vuoi concedere. Questo campo deve essere un oggetto in cui ogni chiave è una stringa di relazione e il valore è un oggetto contenente le estensioni per quella relazione. I client che richiedono queste istruzioni devono essere aggiornati per rispettare questi campi.

Ad esempio, relation_extensions per la relazione delegate_permission/common.handle_all_urls potrebbe avere il seguente aspetto:

  {
    "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": {...}
    }
  }
  

L'API DAL supporta la restituzione di relation_extensions nelle chiamate API quando il parametro return_relation_extensions=true è impostato nella richiesta.

Elenco delle dichiarazioni di esempio

Ecco un elenco di istruzioni del sito web di esempio che contiene istruzioni su siti web e app: http://example.digitalassetlinks.org/.well-known/assetlinks.json

Scalabilità a decine di istruzioni o più

In alcuni casi, un soggetto potrebbe voler fare molte dichiarazioni diverse su target diversi oppure potrebbe essere necessario emettere dichiarazioni da soggetti diversi allo stesso insieme di target. Ad esempio, un sito web potrebbe essere disponibile su molti domini di primo livello per paese diversi e tutti potrebbero voler fare una dichiarazione sulla stessa app mobile.

In queste situazioni, possono essere utili le dichiarazioni di inclusione. Utilizzando questo meccanismo, puoi configurare puntatori da molti principal diversi a una posizione centrale, che definisce le istruzioni per tutti i principal.

Ad esempio, potresti decidere che la posizione centrale deve essere `https://example.com/includedstatements.json`. Questo file può essere configurato in modo da contenere gli stessi contenuti degli esempi precedenti.

Per impostare un puntatore da un sito web al file di inclusione, modifica `https://example.com/.well-known/assetlinks.json` in:

[{
  "include": "https://example.com/includedstatements.json"
}]

Per impostare un puntatore da un'app per Android al file include, modifica `res/values/strings.xml` in:

<resources>
  ...
  <string name="asset_statements">
    [{
      \"include\": \"https://example.com/includedstatements.json\"
    }]
  </string>
</resources>

Ulteriori informazioni

Nel nostro documento delle specifiche è disponibile una spiegazione più dettagliata del formato dell'elenco delle istruzioni e dei concetti sottostanti.