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 dell'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 di 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.

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 ha impostato le norme di gestione dei link corrette:

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 sia destinata ad Android 12.

Stabilire 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 è destinata ad 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

Reimpostare lo stato degli app link Android su un dispositivo

Prima di richiamare manualmente la verifica del dominio su un dispositivo, devi reimpostare lo stato degli app link Android 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 imposta il dispositivo nello stesso stato in cui si trovava prima che l'utente scegliesse le app predefinite per i domini.

Richiamare la procedura di verifica del dominio

Dopo aver reimpostato lo stato degli app link Android su un dispositivo, puoi eseguire la verifica vera e propria. Per farlo, esegui questo comando in una finestra del terminale:

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

Esaminare i risultati della verifica

Dopo aver lasciato un po' di tempo all'agente di verifica per completare le 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 uno 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 qualche altro minuto affinché l' agente di verifica completi le richieste relative alla verifica del dominio, e quindi richiama di nuovo la procedura di verifica del dominio.
verified
Il dominio è stato verificato correttamente per l'app dichiarante.
approved
Il dominio è stato approvato forzatamente, in genere eseguendo un comando della shell.
denied
Il dominio è stato rifiutato forzatamente, in genere eseguendo un comando della shell.
migrated
Il sistema ha conservato il risultato di una procedura precedente che utilizzava la verifica del dominio legacy.
restored
Il dominio è stato approvato dopo che l'utente ha eseguito un ripristino dei dati. Si presuppone che il dominio sia stato verificato in precedenza.
legacy_failure
Il dominio è stato rifiutato da un verificatore legacy. Il motivo specifico del mancato funzionamento non è noto.
system_configured
Il dominio è stato approvato automaticamente dalla configurazione del dispositivo.
Codice di errore 1024 o superiore

Codice di errore personalizzato specifico del verificatore del dispositivo.

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

Chiedere 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.

Verificare se la tua app è già stata 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 una query sullo stato di approvazione utilizzando uno dei seguenti metodi:

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 una 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 non è riuscita per il dominio "example.org", 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.

Fornire il contesto per la richiesta

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

Effettuare la richiesta

Dopo che l'utente ha compreso cosa gli viene chiesto di fare dalla tua app, effettua la richiesta. Per farlo, richiama un intent che includa l'azione dell'intent ACTION_APP_OPEN_BY_DEFAULT_SETTINGS e una stringa di dati corrispondente a package:com.example.pkgper 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 viene richiamato l'intent, gli utenti vedono una schermata delle impostazioni denominata Apri per impostazione predefinita. Questa schermata contiene un pulsante di opzione denominato Apri i link supportati, come mostrato nella Figura 1.

Quando l'utente attiva l'opzione Apri i link supportati, viene visualizzato un insieme di caselle di controllo in una sezione denominata 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 gli utenti selezionano in un secondo momento un link all'interno dei domini che aggiungono, il link si apre automaticamente nella tua app.

Quando il pulsante di opzione è attivato, una sezione nella parte inferiore include caselle di controllo e un pulsante chiamato &quot;Aggiungi link&quot;.
Figura 1. Schermata delle impostazioni di sistema in cui gli utenti possono scegliere quali link aprire nella tua app per impostazione predefinita.
Ogni casella di controllo rappresenta un dominio che puoi aggiungere. I pulsanti della finestra di dialogo sono &quot;Annulla&quot; e &quot;Aggiungi&quot;.
Figura 2. Finestra di dialogo in cui gli utenti possono scegliere altri domini da associare alla tua app.

Aprire nella tua app i domini che non può verificare

La funzione principale della tua app potrebbe essere quella di aprire i 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 una finestra di dialogo o un'attività di transizione che consenta all'utente di aprire il link nell'app proprietaria, se preferisce farlo, fungendo da proxy. Prima di configurare una finestra di dialogo o un'attività di transizione 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 affinché 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 e della ri-verifica pianificata del sistema.
  • Android 14 (livello API 34) e versioni precedenti: il sistema non esegue la ri-verifica periodica in background. In genere, gli aggiornamenti del file vengono rilevati solo quando l'app viene installata o aggiornata.

Testare gli aggiornamenti

Per forzare una ri-verifica su un dispositivo specifico durante i test, puoi disinstallare e reinstallare l'app. Tieni presente, tuttavia, che le cache lato server potrebbero comunque ritardare la distribuzione del file assetlinks.json aggiornato al dispositivo, anche dopo la reinstallazione. Poiché la cache è basata sul tempo, il ritardo in genere si risolve automaticamente se riprovi dopo qualche ora.