Verificare i link per app

Quando android:autoVerify="true" è presente in almeno uno dei filtri per intent della tua app, l'installazione dell'app su un dispositivo con Android 6.0 (livello API 23) o versioni successive fa sì che il sistema verifichi automaticamente gli host associati agli URL nei filtri per intent della tua app. Su Android 12 e versioni successive, puoi anche richiamare manualmente la procedura di verifica per testare la logica di verifica.

Verifica automatica

La verifica automatica del sistema prevede quanto segue:

1. Il sistema esamina tutti i filtri per intent che includono uno dei seguenti elementi:
   • Azione: android.intent.action.VIEW
   • Categorie: android.intent.category.BROWSABLE e android.intent.category.DEFAULT
   • Schema dei dati: http o https
2. Per ogni nome host univoco trovato nei filtri per intent, Android esegue una query sui siti web corrispondenti per il file Digital Asset Links all'indirizzo https://hostname/.well-known/assetlinks.json.

Nota :su Android 11 (livello API 30) e versioni precedenti, il sistema imposta la tua app come gestore predefinito per i pattern URL specificati solo se trova un file Digital Asset Links corrispondente per tutti gli host nel manifest.

Dopo aver confermato l'elenco dei siti web da associare alla tua app e aver verificato che il file JSON ospitato sia valido, installa l'app sul tuo dispositivo. Attendi almeno 20 secondi per il completamento della procedura di verifica asincrona. Utilizza il seguente comando per verificare se il sistema ha verificato la tua app e impostato i criteri di gestione dei link corretti:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Verifica manuale

A partire da Android 12, puoi richiamare manualmente la verifica del dominio per un'app installata su un dispositivo. Puoi eseguire questa procedura indipendentemente dal fatto che la tua app abbia come target Android 12.

Stabilisci una connessione a internet

Per eseguire la verifica del dominio, il dispositivo di test deve essere connesso a internet.

Supportare la procedura di verifica del dominio aggiornata

Se la tua app ha come target Android 12 o versioni successive, il sistema utilizza automaticamente la procedura di verifica del dominio aggiornata.

In caso contrario, puoi attivare manualmente la procedura di verifica aggiornata. Per farlo, esegui questo comando in una finestra del terminale:

adb shell am compat enable 175408749 PACKAGE_NAME

Reimposta lo stato degli Android App Links su un dispositivo

Prima di richiamare manualmente la verifica del dominio su un dispositivo, devi reimpostare lo stato di Android App Links sul dispositivo di test. Per farlo, esegui questo comando in una finestra del terminale:

adb shell pm set-app-links --package PACKAGE_NAME 0 all

Questo comando mette il dispositivo nello stesso stato in cui si trova prima che l'utente scelga le app predefinite per i domini.

Richiama la procedura di verifica del dominio

Dopo aver reimpostato lo stato di Android App Links su un dispositivo, puoi eseguire la verifica. Per farlo, esegui questo comando in una finestra del terminale:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Nota: prima di esaminare i risultati di questo comando, attendi qualche minuto affinché l'agente di verifica completi le richieste relative alla verifica del dominio.

Esamina i risultati della verifica

Dopo aver atteso un po' di tempo per consentire all'agente di verifica di completare le sue richieste, esamina i risultati della verifica. Per farlo, esegui questo comando:

adb shell pm get-app-links PACKAGE_NAME

L'output di questo comando è simile al seguente:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

I domini che superano la verifica hanno lo stato di verifica del dominio verified. Qualsiasi altro stato indica che non è stato possibile eseguire la verifica del dominio. In particolare, lo stato none indica che l'agente di verifica potrebbe non aver ancora completato la procedura di verifica.

Il seguente elenco mostra i possibili valori restituiti dalla verifica del dominio per un determinato dominio:

none

Non è stato registrato nulla per questo dominio. Attendi ancora qualche minuto affinché l'agente di verifica completi le richieste relative alla verifica del dominio, quindi richiama nuovamente la procedura di verifica del dominio.

verified

Il dominio è stato verificato correttamente per l'app dichiarante.

approved

Il dominio è stato approvato forzatamente, di solito eseguendo un comando shell.

denied

Il dominio è stato rifiutato forzatamente, in genere eseguendo un comando shell.

migrated

Il sistema ha conservato il risultato di un processo precedente che utilizzava la verifica del dominio precedente.

restored

Il dominio è stato approvato dopo che l'utente ha eseguito un ripristino dei dati. Si presume che il dominio sia stato verificato in precedenza.

legacy_failure

Il dominio è stato rifiutato da un verificatore legacy. Il motivo specifico dell'errore è sconosciuto.

system_configured

Il dominio è stato approvato automaticamente dalla configurazione dispositivo.

Codice di errore 1024 o superiore

Codice di errore personalizzato specifico per l'analizzatore del dispositivo.

Verifica di aver stabilito una connessione di rete e richiama nuovamente la procedura di verifica del dominio.

Chiedi all'utente di associare la tua app a un dominio

Un altro modo per ottenere l'approvazione della tua app per un dominio è chiedere all'utente di associare la tua app a quel dominio.

Nota: su un determinato dispositivo, è possibile associare una sola app alla volta a un dominio specifico. Se un'altra app è già verificata per il dominio, l'utente deve prima dissociarla dal dominio prima di poter associare la tua app al dominio.

Controlla se la tua app è già approvata per il dominio

Prima di chiedere all'utente, verifica se la tua app è il gestore predefinito per i domini definiti negli elementi <intent-filter>. Puoi eseguire query sullo stato di approvazione utilizzando uno dei seguenti metodi:

• L'API DomainVerificationManager (in fase di runtime).
• Un programma a riga di comando (durante i test).

DomainVerificationManager

Il seguente snippet di codice mostra come utilizzare l'API DomainVerificationManager:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the
// user has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user
        // has associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Programma a riga di comando

Quando testi l'app durante lo sviluppo, puoi eseguire il seguente comando per eseguire query sullo stato di verifica dei domini di proprietà della tua organizzazione:

adb shell pm get-app-links --user cur PACKAGE_NAME

Nell'output di esempio seguente, anche se la verifica dell'app per il dominio "example.org" non è andata a buon fine, l'utente 0 ha approvato manualmente l'app nelle impostazioni di sistema e nessun altro pacchetto è stato verificato per quel dominio.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Puoi anche utilizzare i comandi della shell per simulare la procedura in cui l'utente seleziona l'app associata a un determinato dominio. Una spiegazione completa di questi comandi è disponibile nell'output di adb shell pm.

Nota: il sistema può associare una sola app alla volta a un dominio, anche quando utilizzi i comandi della shell. Alcuni casi speciali, come l'installazione di due varianti di app contemporaneamente, richiedono una gestione speciale per aprire un determinato link web nell'app prevista.

Fornisci il contesto della richiesta

Prima di effettuare questa richiesta di approvazione del dominio, fornisci un contesto per l'utente. Ad esempio, potresti mostrare una schermata iniziale, una finestra di dialogo o un elemento UI simile che spiega all'utente perché la tua app deve essere il gestore predefinito per un determinato dominio.

Effettua la richiesta

Dopo che l'utente ha capito cosa gli viene chiesto di fare, effettua la richiesta. Per farlo, richiama un intent che includa l'azione di intent ACTION_APP_OPEN_BY_DEFAULT_SETTINGS e una stringa di dati corrispondente a package:com.example.pkg per l'app di destinazione, come mostrato nel seguente snippet di codice:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Quando l'intent viene richiamato, gli utenti visualizzano una schermata delle impostazioni denominata Apri per impostazione predefinita. Questa schermata contiene un pulsante di opzione chiamato Apri link supportati, come mostrato nella Figura 1.

Quando l'utente attiva Apri i link supportati, viene visualizzato un insieme di caselle di controllo nella sezione Link da aprire in questa app. Da qui, gli utenti possono selezionare i domini che vogliono associare alla tua app. Possono anche selezionare Aggiungi link per aggiungere domini, come mostrato nella figura 2. Quando in un secondo momento gli utenti selezionano un link all'interno dei domini che aggiungono, il link si apre automaticamente nella tua app.

Figura 1. Schermata delle impostazioni di sistema in cui gli utenti possono scegliere quali link aprire nell'app per impostazione predefinita.

Figura 2. Finestra di dialogo in cui gli utenti possono scegliere altri domini da associare alla tua app.

Apri nella tua app i domini che non può verificare

La funzione principale della tua app potrebbe essere quella di aprire link come terza parte, senza la possibilità di verificare i domini gestiti. In questo caso, spiega agli utenti che, quando selezionano un link web, non possono scegliere tra un'app proprietaria e la tua app (di terze parti). Gli utenti devono associare manualmente i domini alla tua app di terze parti.

Inoltre, valuta la possibilità di introdurre un'attività di dialogo o trampoline che consenta all'utente di aprire il link nell'app proprietaria, se preferisce, fungendo da proxy. Prima di configurare un'attività di questo tipo, configura la tua app in modo che abbia la visibilità del pacchetto nelle app proprietarie che corrispondono al filtro per intent web della tua app.

Latenza di aggiornamento di Digital Asset Links

Quando aggiorni il file assetlinks.json sul tuo server web, il tempo necessario perché queste modifiche vengano applicate sui dispositivi degli utenti finali dipende dalla versione del sistema operativo:

• Android 15 (livello API 35) e versioni successive:il sistema verifica periodicamente i domini in background. La propagazione delle modifiche a tutti i dispositivi degli utenti finali può richiedere fino a sette giorni a causa della memorizzazione nella cache del sistema e della nuova verifica pianificata.
• Android 14 (livello API 34) e versioni precedenti:il sistema non esegue la nuova verifica periodica in background. In genere, gli aggiornamenti al file vengono rilevati solo quando l'app viene installata o aggiornata.

Aggiornamenti dei test

Per forzare una nuova verifica su un dispositivo specifico durante i test, puoi disinstallare e reinstallare l'app. Tuttavia, tieni presente che le cache lato server potrebbero comunque ritardare la pubblicazione del file assetlinks.json aggiornato sul dispositivo, anche dopo la reinstallazione. Poiché la cache è basata sul tempo, il ritardo in genere si risolve automaticamente se riprovi dopo alcune ore.