Testare i link app

Quando implementi la funzionalità di collegamento delle app, devi testare la funzionalità di collegamento per assicurarti che il sistema possa associare la tua app ai tuoi siti web e gestire le richieste di URL come previsto.

Per testare un file di istruzioni esistente, puoi utilizzare lo strumento Generatore ed esaminatore di elenchi di istruzioni.

Le sezioni seguenti descrivono come testare manualmente la verifica degli app link. Se preferisci, puoi testare la verifica dallo strumento Play Deep Links o dall'assistente per app link di Android Studio.

Conferma l'elenco degli host da verificare

Durante il test, devi confermare l'elenco degli host associati che il sistema deve verificare per la tua app. Crea un elenco di tutti gli URL i cui filtri per intent corrispondenti includono i seguenti attributi ed elementi:

  • Attributo android:scheme con un valore di http o https
  • Attributo android:host con un pattern URL di dominio
  • Elemento di azione android.intent.action.VIEW
  • Elemento di categoria android.intent.category.BROWSABLE

Utilizza questo elenco per verificare che in ogni host e sottodominio denominato sia fornito un file JSON Digital Asset Links.

Conferma i file Digital Asset Links

Per ogni sito web, utilizza l'API Digital Asset Links per verificare che il file JSON Digital Asset Links sia ospitato e definito correttamente:

https://digitalassetlinks.googleapis.com/v1/statements:list?
   source.web.site=https://<var>domain.name</var>:<var>optional_port</var>&amp;
   relation=delegate_permission/common.handle_all_urls

Per gli app link dinamici, puoi anche controllare le estensioni delle relazioni.

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urls&return_relation_extensions=true

Nell'ambito della procedura di test, puoi controllare le impostazioni di sistema correnti per la gestione dei link. Utilizza il seguente comando per ottenere un elenco delle policy di gestione dei link esistenti per tutte le app sul dispositivo connesso:

adb shell dumpsys package domain-preferred-apps

Il seguente comando esegue la stessa operazione:

adb shell dumpsys package d

Il comando restituisce un elenco di ogni utente o profilo definito sul dispositivo, preceduto da un'intestazione nel seguente formato:

App linkages for user 0:

Dopo questa intestazione, l'output utilizza il seguente formato per elencare le impostazioni di gestione dei link per l'utente:

Package: com.android.vending
Domains: play.google.com market.android.com
Status: always : 200000002

Questo elenco indica quali app sono associate a quali domini per l'utente:

  • Package : identifica un'app in base al nome del pacchetto, come dichiarato nel manifest.
  • Domains : mostra l'elenco completo degli host i cui link web vengono gestiti da questa app, utilizzando gli spazi vuoti come delimitatori.
  • Status : mostra l'impostazione di gestione dei link corrente per questa app. Un'app che ha superato la verifica e il cui manifest contiene android:autoVerify="true" mostra lo stato always. Il numero esadecimale dopo questo stato è correlato al record delle preferenze di collegamento delle app dell'utente nel sistema Android. Questo valore non indica se la verifica è andata a buon fine.

Esempio di test

Affinché la verifica dei link alle app vada a buon fine, il sistema deve essere in grado di verificare la tua app con ciascuno dei siti web che specifichi in un determinato filtro per intent che soddisfa i criteri per i link alle app. L'esempio seguente mostra una configurazione del manifest con diversi link alle app definiti:

<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>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="www.example2.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="account.example.com" />
        </intent-filter>
    </activity>

      <activity android:name="ThirdActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="https" />
            <data android:host="map.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="market" />
            <data android:host="example.com" />
        </intent-filter>
      </activity>

</application>

L'elenco degli host che la piattaforma tenterebbe di verificare dal manifest precedente è:

www.example.com
mobile.example.com
www.example2.com
account.example.com

L'elenco degli host che la piattaforma non tenterebbe di verificare dal manifest precedente è:

map.example.com (it does not have android.intent.category.BROWSABLE)
market://example.com (it does not have either an "http" or "https" scheme)

Per saperne di più sugli elenchi di istruzioni, consulta Creare un elenco di istruzioni.

A partire da Android 17, puoi utilizzare il flag --debug-link con il comando activity manager (am start) per diagnosticare in che modo il sistema risolve un URL specifico. Questo strumento fornisce un'analisi dettagliata delle app candidate che corrispondono all'intent, insieme alle regole specifiche del manifest dell'app e del file assetlinks.json (per gli app link dinamici) che sono state valutate durante la risoluzione.

Per testare la risoluzione dei link per un URL specifico, esegui il seguente comando in una finestra del terminale:

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

L'output di diagnostica viene stampato sotto l'intestazione App Link Resolution Debug e contiene le seguenti sezioni per aiutarti a comprendere la procedura di risoluzione:

  • Target details: identifica ogni app candidata corrispondente in base al nome del pacchetto e all'attività di destinazione.
  • Corrispondenza filtro intent (AndroidManifest.xml): mostra quali attributi statici nel filtro per intent del manifest (ad esempio scheme, host, path, pathPrefix o pathPattern) corrispondono all'URI.
  • App Link Verification: mostra lo stato di verifica del dominio corrente (ad esempio STATE_SUCCESS).
  • Dynamic App Links: se l'app utilizza regole di corrispondenza degli app link dinamici nel file assetlinks.json, questa sezione elenca ogni regola valutata rispetto all'URI. Ogni regola indica i filtri URI corrispondenti (ad esempio prefissi o pattern di percorso) e un campo allow:
    • allow = 0: una regola di autorizzazione/inclusione (allow: true). Se questa regola corrisponde, l'app è autorizzata ad aprire l'URI.
    • allow = 1: una regola di blocco/esclusione (allow: false / exclude: true). Se questa regola corrisponde, l'app non può aprire l'URI.
    • Nota: una stringa di filtro vuota (filter =) indica un prefisso di percorso vuoto che corrisponde a tutti i percorsi nel dominio (funge da carattere jolly o catch-all).

Esempio di output di debug

Considera un'app (com.example.xyzapp) associata al dominio https://xyz.com che definisce regole dinamiche nel file assetlinks.json per escludere /foo* consentendo tutti gli altri percorsi:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.xyzapp",
      "sha256_cert_fingerprints": ["..."]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"/": "/foo*", "exclude": true},
          {"/": "*"}
        ]
      }
    }
  }
]

Quando diagnostichi l'URL https://xyz.com/foo utilizzando --debug-link:

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

Il comando restituisce la seguente analisi di diagnostica:

--- App Link Resolution Debug ---

URI: https://xyz.com/foo
Resolution: Ambiguous (Multiple apps or Browser fallback)
This usually happens when multiple apps can handle the link and no default is set.

All Matching Candidates:

Target:
  Package: com.example.xyzapp
  Activity: com.example.xyzapp.MainActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"
    Host: 'xyz.com' matched android:host="xyz.com"

App Link Verification:
  Verification status: STATE_SUCCESS
  Dynamic App Links:
    -> Matched Rule 0: UriRelativeFilterGroup { allow = 1, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter = /foo }},  }
    -> Matched Rule 1: UriRelativeFilterGroup { allow = 0, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter =  }},  }

Target:
  Package: org.chromium.webview_shell
  Activity: org.chromium.webview_shell.WebViewBrowserActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"

---------------------------------

Starting: Intent { act=android.intent.action.VIEW dat=https://xyz.com/foo }

In questo esempio, il sistema ha valutato le due regole degli app link dinamici da assetlinks.json:

  • Regola 0 (allow = 1, filter = /foo): generata da {"/": "/foo*", "exclude": true}, questa è una regola di esclusione (allow: false) che blocca gli URL che iniziano con il prefisso del percorso /foo.
  • Regola 1 (allow = 0, filter =): generata da {"/": "*"}, questa è una regola di inclusione (allow: true) con un prefisso di percorso vuoto (filter =), che corrisponde a tutti i percorsi in xyz.com (catch-all).

Come funziona la risoluzione in questo scenario:

  1. Sia la regola 0 sia la regola 1 corrispondono all'URL https://xyz.com/foo.
  2. Le regole degli app link dinamici vengono valutate in ordine sequenziale dall'alto verso il basso (la prima regola corrispondente vince).
  3. Poiché la regola 0 viene visualizzata per prima nell'elenco delle istruzioni ed è una regola di esclusione (allow = 1), ha la precedenza sulla regola di autorizzazione generale (regola 1).
  4. L'app viene quindi esclusa dalla gestione di https://xyz.com/foo, il che fa sì che il sistema torni al browser o visualizzi una finestra di dialogo di disambiguazione.