SHA-256 de assetlinks.json tras Play App Signing: quita la barra del navegador en tu TWA

Esta guía cubre una sola reparación: la asociación entre tu sitio web y la versión que entrega Google Play. No trata la creación de la TWA ni la revisión de la app por parte de Play, que tienen sus propias guías enlazadas más abajo. Cada página de Google citada aquí se revisó el 16 de octubre de 2026, y las fuentes aparecen al final.

Por qué la barra del navegador solo aparece en la instalación desde Play

Chrome verifica una TWA comparando el certificado que firmó la app instalada con las huellas digitales que publica tu sitio web. Cuando esa comprobación falla, la guía de inicio rápido de TWA de Chrome indica que el navegador recurre a mostrar tu sitio como una Custom Tab. Esa alternativa es la barra de direcciones que ves.

Con Play App Signing suele haber dos certificados. Tú firmas el paquete que subes con tu clave de subida, y Google firma los APK que entrega con la clave de firma de apps. La página Android concepts for web developers de Chrome indica que la huella de la clave de firma de apps es la que corresponde a tu app cuando se descarga desde Play Store. Por eso, un archivo que solo incluye tu certificado local funciona en tu escritorio y falla en todos los teléfonos que la instalaron desde Play.

Las dos claves no siempre son distintas. La documentación de firma de apps de Android describe configuraciones en las que la misma clave sirve como clave de firma de apps y como clave de subida. Así que la solución es comparar los certificados reales, no suponer cuál tienes.

Encuentra el SHA-256 de firma de apps en Play Console

La propia documentación de Google da actualmente dos nombres para el mismo lugar. Ambos empiezan en Protected with Play, en el menú izquierdo de tu app.

Las guías más antiguas, incluidas algunas páginas de Google, todavía dicen Release > Setup > App signing o Setup > App integrity. Si solo encuentras esos nombres, estás buscando la misma página con un nombre anterior.

Lee la huella de una clave que tienes tú

Para tu clave de subida o una clave de depuración, keytool de Java imprime el mismo formato. Sustituye el archivo del keystore y el alias por los tuyos y copia la línea etiquetada SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Si gestionas muchas apps, la Google Play Developer API también puede devolver el hash del certificado de los APK que generó Play (el campo certificateSha256Hash de la lista de APK generados). Para una sola corrección, copiarlo desde Play Console es más sencillo.

Escribe y sirve un assetlinks.json correcto

El archivo es un array JSON de declaraciones. Para una TWA, la relación es delegate_permission/common.handle_all_urls, y el destino es tu app de Android: el namespace android_app, tu ID de aplicación exacto y un array de huellas SHA-256. Un archivo mínimo se ve así:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Sustituye com.example.twa por tu ID de aplicación y cada marcador por un SHA-256 completo separado por dos puntos. Elimina la segunda entrada si solo necesitas que se verifiquen las instalaciones desde Play. Solo JSON estricto: sin comentarios, sin comas finales, sin valores SHA-1.

Cómo exige Google que se sirva el archivo

• Ubicación exacta. https://your-domain/.well-known/assetlinks.json, con el punto en .well-known. example.com y www.example.com son orígenes distintos; publica el archivo en cada uno que abra tu app. Una copia en un subdirectorio como /app/.well-known/ no cuenta.
• Un HTTP 200 directo. La documentación de Digital Asset Links de Google dice: “Cualquier respuesta del servidor distinta de HTTP 200 se trata como un error y da como resultado una lista de declaraciones vacía.”
• Sin redirecciones. Las respuestas 301 y 302 no se siguen. Eso incluye un salto de http a https y un salto del dominio sin www a www.
• HTTPS con una cadena de certificados válida, y el encabezado Content-Type: application/json. Una página de inicio de sesión o una página de error HTML que responde con 200 no es un archivo válido.

Comprueba la respuesta en vivo desde cualquier terminal. La primera línea de estado debe ser 200 y el tipo de contenido debe ser JSON, sin ningún 3xx antes:

curl -sI https://example.com/.well-known/assetlinks.json

Más de una huella, más de una app

La guía de asociación de sitios web de Android dice sobre el array de huellas: “Este campo admite varias huellas digitales, que pueden usarse para dar soporte a distintas versiones de tu app, como las versiones de depuración y de producción.” Añade una huella de subida o de depuración solo para las versiones en las que de verdad quieras que ese sitio web confíe. Una versión con un ID de aplicación distinto, como un paquete de depuración aparte, necesita su propia declaración en el array.

Si creaste la TWA con Bubblewrap o PWABuilder

En un proyecto de Bubblewrap existente, añade la huella de Play y vuelve a generar el archivo:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Generar el archivo no es desplegarlo: sube el nuevo assetlinks.json a tu sitio web y compruébalo con curl. bubblewrap validate evalúa tu PWA según criterios de calidad; no comprueba la asociación de firma, así que aprobarlo no demuestra nada sobre la huella. Las instrucciones actuales de PWABuilder dicen lo mismo sobre la firma, “Once you've uploaded your .aab file, Google Play re-signs your app” (una vez que subes tu archivo .aab, Google Play vuelve a firmar tu app), y te indican que añadas la huella de Play al archivo generado. Corregir una huella es un cambio en tu sitio web, no en el binario de la app.

Verifica la asociación y luego prueba la instalación desde Play

Intervienen cuatro capas: el archivo de tu sitio web, la Digital Asset Links API de Google, la verificación de enlaces propia de Android y el navegador que abre tu TWA. Superar una capa no demuestra que se supere la siguiente, así que revísalas en orden y termina en el dispositivo.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

El App Links Assistant de Android Studio (Tools > App Links Assistant) comprueba la asociación de Android App Links y tu manifiesto. Es útil para eso, pero no te dice si tu TWA se abre a pantalla completa; solo la prueba en el dispositivo lo hace.

Avanzado: el estado de verificación propio de Android

En Android 12 y versiones posteriores, la guía de verificación de Android documenta estos comandos para App Links. Sustituye el paquete, ejecuta los dos primeros, espera unos minutos y luego lee el estado:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified describe la verificación de dominios de Android, no si tu TWA se abre sin la interfaz del navegador. Los códigos de 1024 o más son errores específicos del verificador, no un diagnóstico de un SHA-256 incorrecto. Para la TWA en sí, usa el registro de Chrome de arriba.

La huella coincide, pero la barra sigue

Una barra visible no demuestra que el SHA-256 sea incorrecto. Cuando la comprobación anterior devuelve linked: true y la barra sigue ahí, revisa estas causas.

Cuánto tarda en aplicarse un archivo corregido

Google no publica un tiempo de espera único para las TWA, porque intervienen varias cachés y cada una tiene sus propias reglas:

• Tu servidor o CDN puede seguir sirviendo el archivo antiguo. Púrgalo y confirma la respuesta en vivo con curl.
• La Digital Asset Links API indica cuánto tiempo sigue siendo válida cada respuesta en su campo maxAge.
• Android App Links tiene sus propios tiempos. La guía de verificación de Android dice que en Android 15 y versiones posteriores los cambios pueden tardar hasta siete días en llegar a todos los dispositivos, y que en Android 14 y versiones anteriores el archivo normalmente se lee cuando la app se instala o se actualiza.
• El navegador puede conservar su propio estado. Un desarrollador reportó que lo resolvió borrando los datos de Chrome.

Así que purga la caché, confirma el archivo en vivo y reinstala desde Google Play. En un dispositivo de prueba, una instalación nueva o borrar los datos del navegador puede descartar un estado en caché; es un paso de diagnóstico, no algo que debas pedir a cada usuario. No planifiques en torno a un número fijo de horas.

Rechazo, revisión y prueba cerrada

Un assetlinks.json ausente o incorrecto no está documentado como causa de rechazo por sí solo. Lo que describe la documentación es el paso a una Custom Tab con la interfaz del navegador. La revisión es otra cuestión: la política de funcionalidad de Google Play dice “No permitimos apps que fallen, se cierren forzosamente, se congelen o funcionen de forma anómala de cualquier otro modo”, y eso se aplica sea cual sea el estado de tu asociación. Una huella correcta quita la barra; no resuelve la revisión. Si recibiste un rechazo, empieza por la política que se menciona en el correo.

Algunos artículos antiguos dicen que Chrome hará fallar una TWA que no supere sus comprobaciones de calidad. Chromium eliminó ese código QualityEnforcer el 4 de mayo de 2023, así que toma ese consejo como algo histórico y no como una descripción de los navegadores actuales.

Si recibiste un rechazo, parte del motivo indicado en el aviso: el rechazo por Broken Functionality explica paso a paso el aviso de funcionalidad más común. No reconstruyas tu TWA como WebView solo por una barra del navegador. Si tu app salió de un generador con IA, publicar una app hecha con vibe coding en Google Play cubre todo el camino del proyecto a Play.

Preguntas frecuentes

En resumen

Los nombres de los menús de Play Console son el dato que más rápido cambia en esta página. Si las rutas anteriores ya no coinciden con tu Console, busca Play app signing dentro de Protected with Play, o busca app signing en la Console.