Configura asociaciones de sitios web y reglas dinámicas

Para admitir vínculos de la app, debes crear un archivo JSON de Vínculos de recursos digitales llamado assetlinks.json y publicarlo en una ubicación conocida de tu sitio web. Este archivo declara públicamente qué apps están autorizadas para controlar vínculos de tu dominio, y los dispositivos Android recuperarán este archivo de tu servidor para verificar tus vínculos directos.

En el caso de los vínculos directos dinámicos en Android 15 y versiones posteriores, el archivo assetlinks.json también es el lugar donde defines la configuración de tus reglas dinámicas, como los comparadores de patrones para la ruta de acceso, el fragmento y los parámetros de consulta. Los dispositivos Android que ejecutan Android 15 (nivel de API 35) o versiones posteriores que tienen instalados los servicios de Google recuperarán periódicamente el archivo y combinarán tu configuración dinámica con la configuración estática en el manifiesto de la app.

En esta guía, se describe cómo preparar un archivo assetlinks.json y publicarlo en tu sitio web. Si lo prefieres, puedes generar un archivo assetlinks.json con la herramienta Play Deep Links o el Asistente de Android Studio App Links. Para obtener más información, consulta Herramientas para desarrolladores de vínculos de apps.

Cómo declarar la asociación de sitios web

Debes publicar un archivo JSON de Vínculos de recursos digitales en tu sitio web para indicar las apps para Android que están asociadas con el sitio web y verificar los intents de URL de la app. El archivo JSON usa los siguientes campos para identificar aplicaciones asociadas:

  • package_name: El ID de aplicación declarado en el archivo build.gradle de la app.
  • sha256_cert_fingerprints: Son las huellas digitales SHA256 del certificado de firma de tu app. Puedes usar el siguiente comando para generar la huella digital con la herramienta keytool de Java:

keytool -list -v -keystore my-release-key.keystore

  • Este campo admite varias huellas digitales, que pueden usarse para brindar compatibilidad con diferentes versiones de tu app, como depuración y compilación de producción. Si usas la firma de apps de Play para tu app, por lo general, la huella dactilar del certificado que se produce cuando se ejecuta keytool de forma local no coincide con la de los dispositivos de los usuarios. Puedes verificar si usas la firma de apps de Play para tu app en la cuenta de desarrollador de Play Console en Release > Setup > App signing. Si es así, también encontrarás el fragmento JSON de Vínculos de recursos digitales correcto para tu app en la misma página.

En el siguiente ejemplo, el archivo assetlinks.json otorga derechos de apertura de vínculos a una app para Android com.example:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Cómo asociar un sitio web a varias apps

Un sitio web puede declarar asociaciones con varias apps dentro del mismo archivo assetlinks.json. En la siguiente lista de archivos, se muestra un ejemplo de un archivo de instrucción que declara asociación con dos apps, por separado, y reside en https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Distintas apps pueden manejar los vínculos para recursos diferentes en el mismo host web. Por ejemplo, la app1 puede declarar un filtro de intents para https://example.com/articles, y la app2 puede declarar un filtro de intents para https://example.com/videos.

Cómo asociar varios sitios web a una sola app

Varios sitios web pueden declarar asociaciones con la misma app en sus respectivos archivos assetlinks.json. En las siguientes listas de archivos, se muestra un ejemplo de cómo declarar la asociación de example.com y example.net con app1. En la primera lista, se muestra la asociación de example.com con la app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

En la siguiente lista, se muestra la asociación de example.net con la app1. Solo la ubicación donde se alojan estos archivos es diferente (.com y .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Configura reglas dinámicas

Los App Links dinámicos en Android 15 y versiones posteriores te permiten usar reglas de coincidencia de vínculos directos del servidor que funcionan junto con las reglas que definiste de forma estática en el manifiesto de tu app. En tu archivo assetlinks.json, defines reglas dinámicas. Es opcional incluirlo.

Los dispositivos Android que ejecutan Android 15 (nivel de API 35) o versiones posteriores que tienen instalados los servicios de Google recuperarán periódicamente este archivo de tu servidor y combinarán la configuración de tus reglas dinámicas con la configuración estática en el manifiesto de la app. El siguiente es un ejemplo de un archivo assetlinks.json con reglas dinámicas:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Puntos clave sobre el código

  • Los vínculos de aplicaciones dinámicos agregan una nueva extensión de relación de vínculos de recursos digitales llamada dynamic_app_link_components, que es donde configuras tus reglas dinámicas.
  • Las reglas dinámicas pueden incluir comparadores de patrones para la ruta, el fragmento y los parámetros de búsqueda.
  • También puedes marcar cualquier verificador de patrones como excluido para que las URLs coincidentes no abran tu app.
  • En este ejemplo, se muestran comparadores de rutas de acceso ("/"), fragmentos ("#") y parámetros de búsqueda ("?"), así como comparadores excluidos ("exclude").
  • Si alguno de los campos del archivo tiene errores de formato o está vacío, Android descarta las reglas dinámicas y el dispositivo vuelve a las reglas definidas de forma estática en el manifiesto de la app.

Las reglas dinámicas solo pueden especificar reglas que se apliquen dentro del alcance de los dominios que declares en el archivo de manifiesto de tu app. Obtén más detalles a continuación.

Declara reglas dinámicas

Los vínculos universales dinámicos admiten una nueva extensión de relación dynamic_app_link_components, que contiene un array de objetos de reglas. Cada regla se define con comparadores de patrones para rutas de acceso, fragmentos y parámetros de consulta que abrirán tu app. Los comparadores también se pueden excluir de forma individual para que no abran tu app. Todos estos son opcionales.

  • Coincidencia de ruta de acceso
    • Clave: "/"
    • Valor: Cadena única, expresión coincidente para la ruta de URL
  • Coincidencia de fragmentos
    • Clave: "#"
    • Valor: Cadena única, expresión coincidente para el fragmento de URL
  • Coincidencia de parámetros de consulta
    • Tecla: "?"
    • Valor: Diccionario para hacer coincidir pares clave-valor en los parámetros de búsqueda de la URL.
    • Por ejemplo, el diccionario {"?", {"dl": "*", "in_app":"true"} coincidirá con la cadena de búsqueda "?in_app=true&dl=abc".
    • El orden de los pares clave-valor en el diccionario no tiene que coincidir con el orden de los pares en la cadena de consulta. Además, el diccionario no necesita coincidir con todos los pares clave-valor de la cadena de consulta, pero se debe encontrar una coincidencia para cada entrada del diccionario.
    • Por ejemplo, el diccionario también coincidiría con la cadena de búsqueda "?lang=en&in_app=true&tz=pst&dl=abc", pero no con la cadena de búsqueda "?lang=en&tz=pst&dl=abc".
  • Excluido
    • Clave: "exclude"
    • Valor: Es un valor opcional verdadero/falso para cada regla definida en dynamic_app_link_components (consulta el ejemplo).

Puedes usar los siguientes caracteres especiales en los comparadores de patrones:

  • "*" coincide con cero o más caracteres hasta que se encuentra el carácter después del comodín en el patrón en la cadena coincidente.
  • “?” coincide con cualquier carácter
  • "?*" coincide con 1 o más caracteres

No hay otras restricciones de caracteres para los valores.

Ordena las reglas dinámicas

El orden en que se declaran las reglas es importante. Android evalúa cada regla en orden hasta que encuentra una coincidencia.

En el siguiente ejemplo, se muestra cómo el orden puede afectar el control. La primera regla coincide con todas las rutas ("*"), pero excluye las coincidencias (exclude: true), lo que significa que excluye todas las URLs de la apertura de la app. En este caso, la segunda regla que permite "/path1" nunca se evaluará.

dynamic_app_link_components: [
  {​"/": "*", exclude: true},
  {​"/": "/path1"}
]

Sin embargo, en el siguiente ejemplo, la regla "/path1" se declara primero, por lo que se evaluará primero y abrirá la app para una URL que coincida con "/path1". La segunda regla, que excluye todas las URLs de la apertura de la app, se evaluará en segundo lugar, pero solo si la primera regla no coincide.

dynamic_app_link_components: [
  {​"/": "/path1"},
  {​"/": "*", exclude: true}
]

Cómo definir el alcance adecuado de tus reglas dinámicas

Cuando definas tus reglas del servidor para usarlas con vínculos dinámicos para aplicaciones en Android 15 y versiones posteriores, es importante que las definas con el alcance adecuado para que funcionen y complementen los filtros de intents estáticos declarados en el manifiesto de tu app.

Las reglas dinámicas declaradas en el archivo assetlinks.json solo pueden especificar reglas para los hosts que declares en el archivo AndroidManifest.xml de tu app. Las reglas dinámicas no pueden expandir el alcance de las reglas de URL que declaras de forma estática en el manifiesto de tu app.

Por este motivo, te recomendamos que uses este enfoque en todas tus reglas dinámicas y estáticas:

  • En el manifiesto de tu app, establece reglas con el alcance más amplio posible, por ejemplo, declarando solo el esquema y el dominio.
  • Confía en las reglas dinámicas del servidor para realizar ajustes adicionales, como el enrutamiento a nivel de la ruta.

Con esta configuración ideal, podrás agregar de forma dinámica nuevas rutas de App Links en el archivo assetlinks.json según sea necesario, sabiendo que se ajustarán al amplio alcance que estableciste en el manifiesto de la app.

Para que tus reglas se controlen correctamente, declara solo un objeto dynamic_app_link_components en todas las declaraciones de un sitio, una relación y una app determinados.

  • Busca varias declaraciones para el mismo sitio, relación y app que declaren un objeto dynamic_app_link_components.
  • Busca varios objetos dynamic_app_link_components que se declaren en una sola instrucción.

En estos casos, Android no garantiza qué configuración de reglas dinámicas se usará.

Compatibilidad de las reglas dinámicas con configuraciones anteriores de App Links

Si ya admites vínculos de la app, puedes agregar compatibilidad con los vínculos dinámicos directamente en tu archivo assetlinks.json existente. Los campos de relación para verificar tus vínculos de la aplicación siguen siendo los mismos, y puedes agregar los nuevos campos de extensión de relación para las reglas dinámicas sin realizar ningún otro cambio.

Los dispositivos Android que ejecutan Android 14 (nivel de API 34 o anterior) ignoran los nuevos campos de extensión de relación para las reglas dinámicas, mientras que los dispositivos que ejecutan Android 15 y versiones posteriores combinarán esas reglas con las reglas definidas en el manifiesto.

Publica el archivo de verificación JSON

Debes publicar tu archivo de verificación JSON en la siguiente ubicación:

https://domain.name/.well-known/assetlinks.json

Asegúrate de lo siguiente:

  • Se publica el archivo assetlinks.json con el tipo de contenido application/json.
  • Se debe poder acceder al archivo assetlinks.json a través de una conexión HTTPS, independientemente de si los filtros de intents de tu app declaran HTTPS como el esquema de datos.
  • Se debe poder acceder al archivo assetlinks.json sin redireccionamientos (sin redireccionamientos 301 o 302).
  • Si los vínculos de tu app admiten varios dominios de host, debes publicar el archivo assetlinks.json en cada dominio. Consulta Cómo admitir vínculos de aplicaciones para varios hosts.
  • No publiques tu app con URLs de prueba en el archivo de manifiesto que podría no estar disponible para el público (como los archivos que solo están disponibles con una VPN). En esos casos, una solución es configurar variantes de compilación para generar un archivo de manifiesto diferente para las compilaciones de desarrollo.

Consulta las siguientes guías relacionadas: