Verificare i link per app

Quando android:autoVerify="true" è presente in almeno uno dei filtri di intent della tua app, l'installazione dell'app su un dispositivo che esegue Android 6.0 (livello API 23) o versioni successive fa sì che il sistema verifichi automaticamente gli host associati agli URL nei filtri di 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 precedenti, Android esegue query sui siti web corrispondenti per il file Digital Asset Links all'indirizzo https:///.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 affinché la procedura di verifica asincrona venga completata. Utilizza il seguente comando per verificare se il sistema ha verificato la tua app e ha 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.

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

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 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 ripristina lo stato del dispositivo precedente alla scelta delle app predefinite per i domini da parte dell'utente.

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

Nota: prima di esaminare i risultati di questo comando, attendi alcuni minuti per consentire all'agente di verifica di completare le richieste relative alla verifica del dominio.

Esaminare i risultati della verifica

Dopo aver lasciato un po' di tempo all'agente di verifica per completare le richieste, controlla 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, uno 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 che la verifica del dominio può restituire 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, 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, 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 legacy.

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 del mancato caricamento è sconosciuto.

system_configured

Il dominio è stato approvato automaticamente dalla configurazione del dispositivo.

Codice di errore 1024 o superiore

Codice di errore personalizzato specifico per il verificatore del dispositivo.

Verifica di aver stabilito una connessione di rete e richiama di nuovo 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, solo un'app alla volta può essere associata a un dominio specifico. Se un'altra app è già verificata per il dominio, l'utente deve prima dissociare l'altra app dal dominio prima di poter associare la tua app al dominio.

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

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

• L'API DomainVerificationManager (in fase di esecuzione).
• 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 la tua app durante lo sviluppo, puoi eseguire il seguente comando per interrogare lo 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 è 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 un'app a un dominio alla volta, anche quando utilizzi i comandi della shell. Alcuni casi particolari, come l'installazione simultanea di due varianti di app, richiedono una gestione speciale per aprire un determinato link web nell'app prevista.

Fornire il contesto della richiesta

Prima di inviare questa richiesta di approvazione del dominio, fornisci un contesto per l'utente. Ad esempio, puoi mostrare una schermata iniziale, una finestra di dialogo o un elemento UI 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 capito cosa gli chiede di fare la tua app, effettua la richiesta. Per farlo, richiama un intent che includa l'azione ACTION_APP_OPEN_BY_DEFAULT_SETTINGS dell'intent e una stringa di dati corrispondente a package:com.example.pkg per l'app di destinazione, come mostrato nello snippet di codice seguente:

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 chiamata Apri per impostazione predefinita. Questa schermata contiene un pulsante di opzione chiamato Apri link supportati, come mostrato nella Figura 1.

Quando l'utente attiva l'opzione Apri link supportati, viene visualizzato un insieme di caselle di controllo in una sezione chiamata 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.

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

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

Apri i domini nella tua app che non può essere verificata

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 trampolino 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à trampoline, configura la tua app in modo che abbia la visibilità dei pacchetti nelle app proprietarie che corrispondono al filtro per intent web della tua app.