Configura asociaciones de sitios web y reglas dinámicas

Para admitir App Links, 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 los 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 App Links dinámicos en Android 15 o versiones posteriores, el archivo assetlinks.json también es 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 el archivo de forma periódica 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 desde la herramienta Play Deep Links o el Asistente de App Links de Android Studio. Para obtener más información, consulta Herramientas para desarrolladores de App Links.

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: Es el ID de aplicación declarado en el build.gradle archivo 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 digital 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 lo haces, 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 con varias apps

Un sitio web puede declarar asociaciones con varias apps en el 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 con 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 la 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 difiere la ubicación en la que se alojan estos archivos (.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"]
  }
}]

Cómo configurar reglas dinámicas

Los App Links dinámicos en Android 15 o 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. Tu archivo assetlinks.json es donde defines las 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 este archivo de tu servidor de forma periódica y combinarán la configuración de tus reglas dinámicas con la configuración estática en el manifiesto de la app. A continuación, se muestra 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 App Links 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 de acceso, el fragmento y los parámetros de consulta.
  • También puedes marcar cualquier comparador de patrones como excluido para que las URLs coincidentes no abran tu app.
  • En este ejemplo, se muestran comparadores para la ruta de acceso ("/"), el fragmento ("#"), los parámetros de consulta ("?") y los comparadores excluidos ("exclude").
  • Si alguno de los campos del archivo está mal formado o vacío, Android descarta las reglas dinámicas y el dispositivo vuelve a las reglas que se definen 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. Consulta a continuación.

Cómo declarar reglas dinámicas

Los App Links 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: Es una sola cadena, una expresión coincidente para la ruta de URL.
  • Coincidencia de fragmentos
    • Clave: "#"
    • Valor: Es una sola cadena, una expresión coincidente para el fragmento de URL.
  • Coincidencia de parámetros de consulta
    • Clave: "?"
    • Valor: Es un diccionario para hacer coincidir pares clave-valor en los parámetros de consulta de la URL.
    • Por ejemplo, el diccionario {"?", {"dl": "*", "in_app":"true"} coincidirá con la cadena de consulta "?in_app=true&dl=abc".
    • El orden de los pares clave-valor en el diccionario no necesita 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 consulta "?lang=en&in_app=true&tz=pst&dl=abc", pero no con la cadena de consulta "?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 estos 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 único.
  • "?*" coincide con 1 o más caracteres.

No hay otras restricciones de caracteres para los valores.

Cómo ordenar reglas dinámicas

El orden en el 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 de acceso ("*"), 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 es una coincidencia.

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

Si no se encuentran coincidencias en la lista de componentes declarados, la URL no abrirá la app. En el siguiente ejemplo, ninguna de las rutas de acceso coincide con "/path3", por lo que el dispositivo tratará esta ruta de acceso como excluida.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Este comportamiento es importante si deseas que dynamic_app_link_components solo excluya ciertas partes de la URL, pero permita todas las demás. En el siguiente ejemplo, omitir la regla final para permitir todas las rutas de acceso restantes significaría que todas las URLs se excluyen de la app.

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

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

Cuando definas tus reglas del servidor para usarlas con App Links dinámicos en Android 15 y versiones posteriores, es importante definirlas correctamente 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 la app.

Por este motivo, te recomendamos que uses este enfoque en 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 un mayor refinamiento, como el enrutamiento a nivel de la ruta de acceso.

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

Para controlar correctamente tus reglas, declara solo un objeto dynamic_app_link_components en las instrucciones de un sitio, una relación y una app determinados.

  • Busca varias instrucciones 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 casos como estos, Android no garantiza qué configuración de reglas dinámicas se usará.

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

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

Los dispositivos Android que ejecutan Android 14 (nivel de API 34 o versiones anteriores) ignoran los nuevos campos de extensión de relación para 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.

Publicación del 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 mediante una conexión HTTPS, independientemente de si los filtros de intents de la 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 apps 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: