App links flutter permite que un enlace web abra una pantalla concreta de una aplicación Flutter en lugar de limitarse a mostrar una página en el navegador. Configurarlo bien requiere coordinar tres partes: el dominio, los ajustes nativos de Android o iOS y la lógica de navegación dentro de Flutter. Si una de ellas falla, el enlace puede abrir el sitio web, llegar a la pantalla equivocada o no producir ninguna acción.
La dificultad no suele estar en recibir una URL, sino en garantizar que el sistema operativo confíe en el dominio y que la aplicación interprete correctamente la ruta, tanto si ya estaba abierta como si se inicia desde cero. Esta guía recorre ese proceso con criterios prácticos y un ejemplo de enlace a una ficha de producto.
Primero, distingue los enlaces verificados de los enlaces profundos
En Flutter se suele hablar de deep links para cualquier enlace que lleva a un contenido específico de una app. Pero Android App Links y Apple Universal Links son mecanismos más concretos: permiten asociar un dominio web con una aplicación y verificar esa relación. Así, un enlace HTTPS como https://ejemplo.com/productos/42 puede abrir directamente la app instalada.
La diferencia importa. Un esquema personalizado como miapp://productos/42 puede servir para abrir una app, pero no demuestra que el dominio pertenezca a esa aplicación y puede entrar en conflicto con otra app que use el mismo esquema. Los enlaces HTTPS verificados ofrecen una experiencia más coherente y conservan una alternativa web cuando la aplicación no está instalada.
En Android, la asociación se declara en el manifiesto y se valida con un archivo llamado assetlinks.json, alojado en el dominio. En iOS, se configura el dominio asociado en la capacidad correspondiente y se publica un archivo apple-app-site-association. Flutter no sustituye estos requisitos del sistema operativo: el paquete elegido puede entregar la URL a la app, pero no verifica por sí solo el dominio.
Define las rutas antes de tocar la configuración nativa
Antes de editar archivos, conviene decidir qué URLs debe admitir el producto. Por ejemplo, si la aplicación tiene una sección de catálogo, una regla clara podría ser aceptar /productos/{id} y rechazar cualquier ruta que no cumpla ese patrón. Esta definición evita que el manifiesto abra la app para direcciones que luego no sabe resolver.
También hay que determinar qué hacer con los parámetros. Una URL como https://ejemplo.com/productos/42?origen=email contiene una ruta y una consulta. La ruta identifica el contenido; el parámetro puede servir para analítica o atribución, pero no debería ser necesario para que la pantalla cargue. Si se usan enlaces con códigos de invitación o campañas, es preferible validarlos y tratarlos como datos no confiables.
- Ruta reconocida: navegar al detalle solicitado y mostrar un estado de carga mientras se obtiene la información.
- Contenido inexistente: abrir una pantalla de error útil o una sección alternativa, no dejar una vista vacía.
- Usuario sin sesión: conservar la intención del enlace, solicitar acceso y continuar después del inicio de sesión.
- URL desconocida: enviar al inicio o al navegador integrado según las reglas del producto.
Esta política debe existir antes de implementar la recepción. De lo contrario, los enlaces pueden funcionar en una demo y fallar en escenarios habituales, como una sesión cerrada o un producto eliminado.
Configura Android y iOS como asociaciones independientes
En Android, el intent filter debe declarar la acción de visualización, las categorías necesarias y el dominio HTTPS que se quiere admitir. En muchos proyectos se limita el filtro a rutas concretas mediante un prefijo o una regla de ruta, en lugar de capturar todas las direcciones del sitio. Además, para que Android trate el enlace como un App Link verificado, el dominio debe publicar el archivo /.well-known/assetlinks.json con el nombre del paquete y la huella del certificado correspondiente.
La huella debe corresponder a la firma de la aplicación distribuida. Un error frecuente es publicar la huella del certificado de depuración y probar una versión firmada para producción, o confundir la clave de carga con la clave de firma que utiliza la tienda. En consecuencia, la verificación puede funcionar en un entorno y fallar después de publicar la app. Conviene revisar la configuración de firma de cada canal de distribución y probar el dominio real.
En iOS, añade el dominio con el prefijo applinks: en Associated Domains y publica el archivo de asociación de Apple en el servidor. El archivo debe servirse correctamente, sin depender de una redirección que cambie su ubicación. En él se relacionan el identificador del equipo, el identificador de la app y las rutas permitidas. Una ruta excluida o un identificador mal escrito puede impedir que el sistema entregue el enlace a la aplicación.
Android e iOS no comparten el mismo archivo ni el mismo procedimiento de verificación. Configurar una plataforma no configura automáticamente la otra. Si existen dominios de pruebas, subdominios o versiones distintas de la app, cada asociación debe contemplarlos de forma explícita. Por ejemplo, www.ejemplo.com y ejemplo.com son hosts diferentes a efectos de configuración.
Recibe el enlace en Flutter sin perder los arranques en frío
Una vez que el sistema operativo puede abrir la aplicación, hace falta procesar la URL en Flutter. El paquete app_links es una opción habitual para escuchar enlaces entrantes y obtener el enlace inicial que causó el arranque. La implementación debe cubrir ambos casos: la app ya estaba activa y recibió un enlace, o estaba cerrada y se abrió desde ese enlace.
El flujo conceptual es sencillo: al iniciar la aplicación, se consulta el enlace inicial y se escucha el flujo de nuevos enlaces. Cada URL se analiza, se valida y se transforma en una intención de navegación. No conviene crear un listener nuevo cada vez que se reconstruye una pantalla; suele ser más robusto centralizar la suscripción en un servicio o en el nivel de aplicación y cancelar la suscripción cuando deja de ser necesaria.
Por ejemplo, ante https://ejemplo.com/productos/42, el analizador puede extraer el segmento 42 y solicitar al sistema de navegación que abra la ruta de detalle. Si se utiliza un router declarativo, como una configuración basada en rutas, la URL debe convertirse en una ruta admitida por ese router. Si se usa navegación imperativa, hay que evitar enviar la orden antes de que el árbol de navegación esté listo.
Este último punto explica muchos fallos intermitentes: el enlace se recibe durante el arranque, pero se intenta navegar antes de que la aplicación haya creado su navegador o restaurado el estado inicial. Una solución habitual es guardar temporalmente la intención y procesarla cuando la navegación esté preparada. Si se requiere autenticación, se conserva el destino pendiente y se continúa tras validar la sesión.
También es necesario evitar procesar dos veces el mismo enlace. Algunas combinaciones de configuración, ciclo de vida o versiones del plugin pueden hacer que la URL inicial y un evento posterior parezcan duplicados. La capa de navegación puede comparar la última intención procesada o aplicar una política idempotente para que una repetición no apile pantallas idénticas.
Prueba el recorrido completo, no solo la función de navegación
Ver que una URL abre una pantalla mientras se ejecuta la app desde el IDE no demuestra que los enlaces estén correctamente configurados. La prueba debe incluir dominio, sistema operativo, instalación, ciclo de vida y destino de navegación. Una matriz breve ayuda a descubrir diferencias que de otro modo aparecen únicamente en producción.
- Prueba con la aplicación instalada y cerrada, tocando el enlace desde un mensaje o una página web.
- Repite la prueba con la app abierta en primer plano y en segundo plano.
- Comprueba qué sucede cuando la app no está instalada: el enlace debe conservar una salida web razonable.
- Ensaya una ruta válida, una ruta desconocida, un identificador inexistente y parámetros de consulta inesperados.
- Verifica por separado el dominio principal, los subdominios utilizados y las versiones de pruebas.
- Después de cambiar archivos de asociación o certificados, vuelve a probar en un dispositivo con una instalación limpia cuando sea necesario.
En Android, las herramientas del sistema permiten inspeccionar la verificación del dominio y lanzar intents de prueba. En iOS, la comprobación depende también de la asociación publicada y de que el dispositivo haya actualizado esa información. No es aconsejable concluir que la configuración está rota solo porque un cambio recién publicado no se refleja de inmediato; primero hay que confirmar el archivo, la firma, el host y la instalación utilizados.
Errores que conviene resolver antes del lanzamiento
El enlace siempre abre el navegador
Comprueba que el dominio coincida exactamente, que el archivo de asociación sea accesible y válido y que la app instalada use el identificador y la firma esperados. En Android, revisa además que el filtro admita el esquema HTTPS y la ruta. En iOS, confirma Associated Domains y las reglas de rutas del archivo de Apple.
La app se abre, pero muestra el inicio
En este caso, la asociación puede funcionar y el problema estar en el tratamiento de la URL. Registra de forma controlada el enlace inicial y los eventos recibidos, revisa el análisis de segmentos y comprueba que el router acepte la ruta resultante. No registres datos sensibles de consulta en producción sin una razón y una política de privacidad adecuadas.
Funciona en pruebas y falla tras publicar
Compara la firma real, el identificador de paquete o bundle y los dominios configurados entre compilaciones. Los entornos de desarrollo suelen utilizar credenciales y hosts distintos. Mantener una lista explícita de dominios por entorno y automatizar la validación de los archivos de asociación reduce errores de configuración manual.
Un caso frecuente es el de una campaña que envía a https://www.ejemplo.com/productos/42, mientras la aplicación solo declara ejemplo.com. Aunque ambos dominios muestren la misma web, el sistema operativo puede tratarlos como asociaciones distintas. La solución no es ampliar todos los filtros indiscriminadamente, sino incorporar de forma consciente los hosts que realmente se publican.
Decide qué nivel de implementación necesita el producto
Para una aplicación pequeña, con unas pocas rutas estables, una recepción centralizada y reglas sencillas pueden ser suficientes. En un producto con campañas, autenticación, enlaces compartidos y múltiples tipos de contenido, hace falta una capa de enrutamiento más formal: validación de URL, resolución de destino, gestión de sesión, analítica y tratamiento de errores.
App links flutter no consiste únicamente en conectar una URL con una pantalla. La asociación verificada hace que el sistema confíe en el dominio; el plugin entrega el evento a Flutter; y la aplicación decide de forma segura qué hacer con él. Antes de publicar, conviene probar enlaces con la app instalada y cerrada, con una sesión pendiente y con contenido inválido. Ese recorrido completo convierte App links flutter en una función fiable, útil para compartir contenido y compatible con una alternativa web sensata.
