Cómo verificar los vínculos de la app

Cuando android:autoVerify="true" está presente en al menos uno de los filtros de intents de tu app, instalar tu app en un dispositivo que ejecuta Android 6.0 (nivel de API 23) o una versión posterior hace que el sistema verifique automáticamente los hosts asociados con las URLs en los filtros de intents de tu app. En Android 12 y versiones posteriores, también puedes invocar el proceso de verificación de forma manual para probar la lógica de verificación.

Verificación automática

La verificación automática del sistema incluye lo siguiente:

1. El sistema inspecciona todos los filtros de intents que incluyen cualquiera de los siguientes elementos:
   • Acción: android.intent.action.VIEW
   • Categorías: android.intent.category.BROWSABLE y android.intent.category.DEFAULT
   • Esquema de datos: http o https
2. Por cada nombre de host único que se encuentra en los filtros de intents anteriores, Android consulta los sitios web correspondientes para el archivo de Digital Asset Links en https:///.well-known/assetlinks.json.

Nota: En Android 11 (nivel de API 30) y versiones anteriores, el sistema establece tu app como el controlador predeterminado para los patrones de URL especificados solo si encuentra un archivo de Digital Asset Links coincidente para todos los hosts del manifiesto.

Una vez que confirmes la lista de sitios web asociados con tu app y que hayas confirmado que el archivo JSON alojado es válido, instala la app en tu dispositivo. Espera al menos 20 segundos a que se complete el proceso de verificación asíncrono. Usa el siguiente comando para comprobar si el sistema verificó tu app y configuró las políticas de control de vínculos correctas:

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

Verificación manual

A partir de Android 12, puedes invocar de forma manual la verificación del dominio para una app instalada en un dispositivo. Puedes realizar este proceso independientemente de si tu app se orienta a Android 12.

Establece una conexión a Internet

Para realizar la verificación del dominio, el dispositivo de prueba debe estar conectado a Internet.

Admite el proceso actualizado de verificación del dominio

Si tu app se orienta a Android 12 o versiones posteriores, el sistema usará automáticamente el proceso actualizado de verificación del dominio.

De lo contrario, puedes habilitarlo de forma manual. Para ello, ejecuta el siguiente comando en una ventana de la terminal:

adb shell am compat enable 175408749 PACKAGE_NAME

Restablece el estado de Android App Links en un dispositivo

Antes de invocar de forma manual la verificación del dominio en un dispositivo, debes restablecer el estado de Android App Links en el dispositivo de prueba. Para ello, ejecuta el siguiente comando en una ventana de la terminal:

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

Este comando coloca el dispositivo en el mismo estado en el que se encuentra antes de que el usuario elija las apps predeterminadas para cualquier dominio.

Invoca el proceso de verificación del dominio

Después de restablecer el estado de Android App Links en un dispositivo, puedes realizar la verificación en sí. Para ello, ejecuta el siguiente comando en una ventana de la terminal:

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

Nota: Antes de consultar los resultados de este comando, espera unos minutos hasta que el agente de verificación termine las solicitudes relacionadas con la verificación del dominio.

Consulta los resultados de verificación

Después de esperar un poco para que el agente de verificación finalice sus solicitudes, consulta los resultados. Para ello, ejecuta el siguiente comando:

adb shell pm get-app-links PACKAGE_NAME

El resultado de este comando es similar al siguiente:

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

Los dominios que aprueban la verificación de manera correcta tienen un estado de verificación del dominio de verified. Cualquier otro estado indica que no se pudo realizar esta verificación. En particular, el estado de none indica que es posible que el agente de verificación todavía no completó el proceso.

En la siguiente lista, se mencionan los posibles valores que puede mostrar la verificación para un dominio determinado:

none

No se registró nada para este dominio. Espera unos minutos más para que el agente de verificación termine las solicitudes relacionadas con la verificación del dominio. Luego, vuelve a invocar el proceso.

verified

Se verificó, de manera correcta, el dominio para la app que lo declara.

approved

El dominio se aprobó de manera forzosa, por lo general, mediante la ejecución de un comando de shell.

denied

El dominio se rechazó de manera forzosa, por lo general, mediante la ejecución de un comando de shell.

migrated

El sistema conserva el resultado de un proceso anterior que usó la verificación heredada del dominio.

restored

Se aprobó el dominio después de que el usuario restableció los datos. Se supone que el dominio se verificó con anterioridad.

legacy_failure

Un verificador heredado rechazó el dominio. Se desconoce el motivo específico de la falla.

system_configured

La configuración del dispositivo aprobó el dominio automáticamente.

Código de error de 1024 o superior

Es un código de error personalizado y específico del verificador del dispositivo.

Vuelve a verificar si estableciste una conexión de red y vuelve a invocar el proceso de verificación del dominio.

Solicítale al usuario que asocie la app con un dominio

Otra manera de obtener la aprobación de la app para un dominio es solicitarle al usuario que la asocie con ese dominio.

Nota: En un dispositivo determinado, solo se puede asociar una app a la vez con un dominio particular. Si ya se verificó otra app para el dominio, el usuario primero debe desvincular esa otra app del dominio antes de que pueda asociar tu app con este.

Verifica si ya se aprobó la app para el dominio

Antes de solicitarle al usuario que realice una acción, verifica si la app es el controlador predeterminado para los dominios que defines en los elementos <intent-filter>. Puedes consultar el estado de aprobación mediante uno de los siguientes métodos:

• La API de DomainVerificationManager (en el tiempo de ejecución).
• Un programa de línea de comandos (durante las pruebas).

DomainVerificationManager

En el siguiente fragmento de código, se muestra cómo usar la API de 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);
    }
}

Programa de línea de comandos

Cuando pruebes la app durante el desarrollo, puedes ejecutar el siguiente comando para consultar el estado de verificación de los dominios que posee la organización:

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

En el siguiente resultado de ejemplo, a pesar de que la app no aprobó la verificación del dominio "example.org", el usuario 0 aprobó de forma manual la app en la configuración del sistema, y no se verificó ningún otro paquete para ese 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

También puedes usar comandos de shell para simular el proceso en el que el usuario selecciona qué app está asociada a un dominio determinado. Puedes encontrar una explicación completa de estos comandos en el resultado de adb shell pm.

Nota: El sistema solo puede asociar una app a la vez con un dominio, incluso cuando usas comandos de shell. En algunos casos especiales, como la instalación simultánea de dos variantes de apps, se requiere un control especial para abrir un vínculo web determinado en la app que deseas usar.

Brinda contexto para la solicitud

Antes de realizar esta solicitud para aprobar el dominio, bríndale contexto al usuario. Por ejemplo, puedes mostrarle una pantalla de presentación, un diálogo o un elemento de la IU similar que le explique al usuario por qué la app debería ser el controlador predeterminado para un dominio particular.

Realiza la solicitud

Una vez que el usuario comprenda lo que la app le solicita que haga, realiza la solicitud. Para hacerlo, invoca un intent que incluya la acción de intent ACTION_APP_OPEN_BY_DEFAULT_SETTINGS y una string de datos que coincida con package:com.example.pkg para la app de destino, como se muestra en el siguiente fragmento de código:

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

Cuando se invoca el intent, los usuarios ven la pantalla de configuración Abrir de forma predeterminada. En esta pantalla, se incluye el botón de selección Abrir vínculos admitidos, como se muestra en la figura 1.

Cuando el usuario activa Abrir vínculos admitidos, aparece un conjunto de casillas de verificación en una sección llamada Vínculos para abrir en esta app. Desde allí, los usuarios pueden seleccionar los dominios que desean asociar con tu app. También pueden seleccionar Agregar vínculo para agregar dominios, como se muestra en la figura 2. Después, cuando los usuarios seleccionen cualquier vínculo dentro de los dominios que agreguen, este se abrirá automáticamente en la app.

Figura 1: Pantalla de configuración del sistema, en la que los usuarios pueden elegir qué vínculos se abren en la app de forma predeterminada.

Figura 2: Diálogo en el que los usuarios pueden elegir dominios adicionales para asociarlos con la app.

Abre dominios de la app que no se pueden verificar

Es posible que la función principal de la app sea abrir vínculos como un tercero, sin la capacidad de verificar sus dominios controlados. Si este es el caso, explícales a los usuarios que, en el momento en que seleccionen un vínculo web, no podrán elegir entre una app propia y tu app (de terceros). Los usuarios deben asociar de forma manual los dominios con la app de terceros.

Además, considera introducir un diálogo o una actividad de trampolín que le permita al usuario abrir el vínculo en la app propia si prefiere hacerlo, como un proxy. Antes de configurar un diálogo o una actividad de trampolín, configura la app para que tenga visibilidad del paquete en las apps propias que coincidan con el filtro de intents web de tu app.