8 min de lectura

App Links Android: assetlinks.json, verificación y fallos comunes

Cómo configurar Android App Links con assetlinks.json, SHA-256 correcto (Play App Signing), autoVerify, verificación adb y los fallos más comunes. Notas Flutter/RN e iOS AASA.

Portada: App Links Android, con tarjeta assetlinks.json que muestra .well-known, SHA-256, autoVerify y Verificar

Los App Links Android (Android App Links) son enlaces https (también pueden declarar http) que el sistema asocia a tu app después de verificar tu dominio con un archivo assetlinks.json. A diferencia de un deep link “suelto” con esquema custom (myapp://), un App Link verificado puede abrir tu app sin el diálogo de elegir navegador cuando todo está bien configurado. Esta guía ES-CO te lleva del intent filter al SHA-256 correcto (sobre todo con Play App Signing), a la verificación y a los fallos que más se buscan: android app links not working, path de .well-known y verify app links.

Según la documentación de Android Developers, los App Links son deep links que usan el esquema HTTP o HTTPS y que Android verifica como asociados a tu sitio web. El flujo oficial resume tres piezas:

  1. Un intent filter en el manifest con android:autoVerify="true".
  2. Una asociación de sitio publicada en Digital Asset Links (assetlinks.json).
  3. La verificación automática al instalar (Android 6.0+) o manual en dispositivos más nuevos.

Un deep link clásico con esquema propio puede abrir la app, pero no pasa por esa verificación de dominio. Los App Links apuntan a URLs reales de tu web (https://tudominio.com/producto/123) y, si la verificación falla, el sistema vuelve al comportamiento habitual (a menudo el navegador u otro handler).

Intent filter con autoVerify

En el AndroidManifest.xml, declara al menos un filtro así (ejemplo genérico; adapta host y activity):

<activity android:name=".MainActivity" android:exported="true">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="http" />
    <data android:scheme="https" />
    <data android:host="www.example.com" />
  </intent-filter>
</activity>

Puntos clave de la guía Add intent filters for App Links:

  • android:autoVerify="true" es obligatorio para App Links: indica al sistema que intente verificar el host contra tu assetlinks.json.
  • Incluye action VIEW y categorías DEFAULT + BROWSABLE.
  • Declara esquemas http y https según la doc; los hosts van en elementos <data>.
  • Varios <data> en el mismo filtro se combinan: si necesitas combinaciones distintas de host/path, usa filtros separados.
  • En Android 12+, si declaras varios hosts, el sistema puede verificarlos de forma independiente; en Android 11 y menor, la verificación del filtro exige que todos los hosts del filtro tengan un DAL válido.

Asegúrate de que el nombre de paquete del manifest coincida exactamente con el que pondrás en el JSON.

El protocolo Digital Asset Links fija la ubicación oficial del statement list:

https://tudominio/.well-known/assetlinks.json

Cualquier otro path o nombre no es válido para ese sitio. Android consulta esa URL por HTTPS al verificar el host.

Ejemplo (marcadores; no copies fingerprints reales a ciegas)

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.ejemplo.miapp",
    "sha256_cert_fingerprints": [
      "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
    ]
  }
}]

Notas del formato oficial:

  • El archivo es un array JSON ([ ... ]), no un objeto suelto { ... }.
  • relation usa delegate_permission/common.handle_all_urls.
  • target.namespace es android_app, con package_name y sha256_cert_fingerprints.
  • Puedes listar varias statements (varias apps o fingerprints) dentro del mismo array.
  • Sirve el archivo por HTTPS, idealmente con Content-Type: application/json, sin cadenas de redirects problemáticas y sin que robots u otras reglas bloqueen el path .well-known.

Si usas varios hosts (www y mobile, o subdominios distintos), cada host necesita su propio archivo accesible, salvo que declares un wildcard (*.example.com): en ese caso el archivo va en el host raíz (https://example.com/.well-known/assetlinks.json), según la documentación de intent filters.

SHA-256: el error #1 con Play App Signing

sha256_cert_fingerprints debe ser la huella SHA-256 del certificado con el que se firma la app que instala el usuario. Con Play App Signing, Google vuelve a firmar con la app signing key; la upload key es la que usas para subir el AAB. Si pones en assetlinks.json el SHA de la clave de carga y en producción la app va firmada con la de Play, la verificación falla aunque el JSON “se vea bien”.

Dónde mirar en la práctica:

Muchos equipos ponen ambas fingerprints (upload + signing) en el array mientras depuran, o al menos la de producción que usa Play. Revisa también que el package_name no tenga typo frente al applicationId / namespace.

  1. Publica un assetlinks.json válido y alcanzable por HTTPS en .well-known.
  2. Instala la app en un dispositivo con Android 6.0+; con autoVerify, el sistema intenta verificar los hosts.
  3. Espera un momento (la doc de verificación sugiere esperar al menos unos segundos en el flujo de prueba) y prueba abrir un enlace del dominio.
  4. En Android 12+ puedes forzar y revisar el estado con adb (paquete de ejemplo com.ejemplo.miapp):
    • Reset: adb shell pm set-app-links --package com.ejemplo.miapp 0 all
    • Re-verify: adb shell pm verify-app-links --re-verify com.ejemplo.miapp
    • Estado: adb shell pm get-app-links com.ejemplo.miapp
      Busca dominios en estado verified. Otros estados (none, legacy_failure, códigos ≥1024, etc.) indican que aún no terminó o que falló.
  5. Android Studio incluye App Links Assistant para revisar filtros y el archivo (aparece en autocomplete de “app links assistant”).

Si cambias el JSON en el servidor: en Android 15+ el sistema puede re-verificar en background (la doc menciona propagación que puede tardar días por caché/programación); en Android 14 y menor suele dependar más de reinstalar o actualizar la app. En pruebas, desinstalar/reinstalar ayuda, pero la caché del servidor también puede retrasar el archivo nuevo.

  • ¿El JSON está exactamente en https://HOST/.well-known/assetlinks.json sin redirect raro?
  • ¿Es un array con relation, package_name y SHA-256 correctos?
  • ¿El SHA es el de la app signing key de Play (no solo upload/debug)?
  • ¿El intent filter tiene autoVerify, VIEW, DEFAULT, BROWSABLE y el mismo host?
  • ¿Hay varios hosts y falta el archivo en alguno? (crítico en Android ≤11)
  • ¿El dominio se abre en otra app “hermanada” instalada más reciente? (varias apps asociadas al mismo path)
  • ¿Probaron verificación manual en Android 12+ y el estado no es verified?

Flutter y React Native (notas prácticas)

En Flutter y React Native el mecanismo del sistema es el mismo: hay que tocar el AndroidManifest nativo (o el plugin que lo genera), publicar assetlinks.json y usar el SHA correcto de la build que llega al dispositivo. Plugins como uni_links / app_links (Flutter) o Linking + intent filters (RN/Expo) no sustituyen la verificación DAL: solo te ayudan a recibir la URL cuando Android ya resolvió el intent. Si publicas con Flutter en Play, alinea el applicationId y la firma con tu checklist de publicación y con publicar una app Flutter en Play Store.

En iOS el equivalente conceptual son Universal Links, asociados con el archivo Apple App Site Association (AASA), a menudo en /.well-known/apple-app-site-association, más la capability Associated Domains. No uses assetlinks.json para iOS ni el AASA para Android: son protocolos distintos. Si tu producto es multiplataforma, mantén dos archivos y dos configuraciones nativas; el autocomplete mezcla mucho “app links android universal links ios” porque los equipos buscan ambas.

FAQ

Casi siempre: SHA-256 incorrecto (upload vs signing), path distinto de /.well-known/assetlinks.json, JSON que no es un array, redirect/HTTP, o intent filter sin autoVerify / host mal escrito. Revisa el estado con pm get-app-links en Android 12+.

En https://tu-host/.well-known/assetlinks.json, como array con delegate_permission/common.handle_all_urls y un target android_app (package + SHA-256). Otro nombre o carpeta no cuenta como statement list oficial.

Instala la app con autoVerify, espera la verificación automática y, en Android 12+, usa pm verify-app-links --re-verify y pm get-app-links. El App Links Assistant de Android Studio también ayuda en desarrollo.

¿Qué SHA-256 pongo si uso Play App Signing?

El de la clave de firma de la app que muestra Play Console (la que firma lo que instala el usuario). La de carga sola suele bastar solo para builds locales firmadas con esa keystore.

No. Los deep links custom usan esquemas propios y no pasan por Digital Asset Links. Los App Links usan HTTP(S) + verificación de dominio.

Es la contraparte de Apple (AASA + Associated Domains). Menciónala en tu checklist multiplataforma, pero configura archivos y consolas por separado.


Cuando ya tengas dominio, paquete y firma alineados, el resto del release en Play (AAB, ficha, capturas, política) sigue el flujo habitual: vuelve al checklist para publicar en Google Play, genera capturas con el generador de screenshots o una política con el generador de política de privacidad, o empieza desde AppConsol.

Sigue aprendiendo