Enlaces universales y enlaces profundos: el traspaso de la web a la app, bien hecho

Los enlaces universales son el mecanismo de Apple que permite que un enlace https abra tu app de iOS directamente, en lugar de Safari. El equivalente en Android se llama App Links. Ambos recurren automáticamente al navegador cuando la app no está instalada. Y ambos dependen de un archivo de propiedad firmado, alojado en tu propio dominio: apple-app-site-association para iOS, assetlinks.json para Android. Desde iOS 14, el formato del archivo de Apple usa una clave "components" en lugar de la antigua lista plana "paths", lo que cambia cómo se escriben las coincidencias de ruta.

Antes de empezar

Los enlaces universales resuelven un problema que los esquemas de URL personalizados no pueden resolver. Un esquema como myapp:// puede registrarlo más de una app, y ni iOS ni Android tienen forma de confirmar cuál es la propietaria real. Un enlace universal o un App Link de Android ata el traspaso a una URL https:// real, en un dominio que tú controlas, demostrado con un archivo firmado que el sistema operativo descarga y verifica. Por eso también se describe a los Smart App Banners y a los enlaces universales como complementarios, no redundantes. Un banner es un aviso de descubrimiento que todavía le cuesta un toque al visitante; un enlace universal bien configurado elimina ese toque por completo.

Antes de tocar código, confirma que hay cuatro cosas en su lugar: un dominio que controles de principio a fin, HTTPS en ese dominio sin excepciones, un Team ID y un App ID de Apple Developer para el lado de iOS, y la huella del certificado de firma de la versión de lanzamiento de la app de Android para el lado de Android. Otras capacidades de iOS sujetas a entitlements siguen este mismo patrón. La configuración de notificaciones push y WidgetKit y Live Activities necesitan primero un archivo del lado del servidor o un certificado correcto, antes de que el entitlement del lado de la app haga absolutamente nada.

Paso a paso: alojar y dar forma al archivo AASA

El archivo debe llamarse exactamente apple-app-site-association, sin extensión, alojado en la raíz de tu servidor web y, por convención, duplicado en /.well-known/. Debe servirse por HTTPS. La propia guía de resolución de problemas de Apple es explícita: debe servirse sin ninguna redirección. Una respuesta 3xx en esa ruta rompe la validación en silencio, sin ningún mensaje de error que señale la causa.

Desde iOS 14, la sección applinks del archivo usa un arreglo components en lugar de la antigua clave paths. Cada entrada de ese arreglo es un diccionario que puede comparar la ruta, la consulta y el fragmento de la URL. Solo la ruta se compara de verdad a efectos de coincidencia. Los parámetros de consulta y el fragmento se ignoran, así que un parámetro presente en un enlace y ausente en otro no cambia si el enlace abre la app. Una propiedad exclude dentro de una entrada de components permite excluir una ruta concreta, un enlace de cierre de sesión o una redirección antigua, por ejemplo, que debe quedarse dentro de Safari en lugar de abrir la app. En Xcode, añade la capacidad Associated Domains con una entrada como applinks:tudominio.com, que coincida exactamente con el dominio donde vive el archivo AASA.

Paso a paso: replicarlo en Android

Los App Links de Android usan un archivo de Digital Asset Links, assetlinks.json, publicado en https://tudominio.com/.well-known/assetlinks.json. La documentación de Google fija las mismas reglas base que las de Apple: HTTPS, tipo de contenido application/json, accesible sin redirecciones. El intent filter de la app necesita android:autoVerify="true" en el <intent-filter> correspondiente. Cuando la app se instala, Android descarga assetlinks.json y comprueba el valor sha256_cert_fingerprints contra el certificado de firma real de la app, antes de concederle el derecho a abrir los enlaces coincidentes de forma automática y evitar el cuadro de selección de app.

Desde Android 15, los Dynamic App Links permiten actualizar qué rutas se reclaman editando assetlinks.json en el servidor, sin necesidad de una nueva compilación de la app. Esa es una diferencia operativa importante frente a iOS, donde un cambio de ruta sigue yendo dentro de una actualización de la app en la mayoría de los casos.

Prueba ambas plataformas de la misma forma: en un dispositivo donde la app ya esté instalada, y en un dispositivo limpio o una imagen de simulador recién restaurada sin ella. Un enlace que abre correctamente en un dispositivo que has probado una docena de veces puede seguir fallando para un usuario nuevo si el archivo AASA o assetlinks.json cambió después de que ese dispositivo lo descargara por última vez. Ambas plataformas almacenan en caché el resultado de la verificación en lugar de comprobarlo en cada toque.

Verificar antes de publicar

Apple publica una App Search API Validation Tool que comprueba el archivo AASA de un dominio e indica si la sección de enlaces universales pasa. Ejecútala contra el dominio de producción, no contra un subdominio de pruebas, ya que la capacidad Associated Domains debe coincidir exactamente con el host donde vive el archivo. En Android, adb shell pm get-app-links <package> indica qué dominios ha verificado con éxito la app instalada. Es la forma más rápida de confirmar que el intercambio con assetlinks.json se completó de verdad, en lugar de caer en silencio en un cuadro de diálogo de selección.

Lleva un registro de la última vez que cambió cada archivo. Ambos sistemas operativos almacenan en caché la verificación, así que una corrección en el archivo AASA o en assetlinks.json no surte efecto para un usuario hasta que el sistema operativo lo vuelve a descargar, normalmente en la siguiente instalación o actualización de la app, no de inmediato.

Diseñar la página alternativa

Un enlace universal que termina en una página web cuando la app no está instalada necesita que esa página haga algo útil, no que cargue un callejón sin salida. La guía de Google sobre enlaces profundos describe el patrón estándar: ser propietario de la URL de destino, hacer que esa página intente el traspaso a la app, y si la app no responde, mantener al visitante en esa misma página con un camino claro para instalarla. No redirijas una segunda vez ni muestres un 404 genérico. El visitante ya realizó la acción que debía funcionar. La página alternativa es donde lo recibes.

Un estudio que desarrolla apps de iOS como oficio, Kallos Labs incluido, trata esta página alternativa y el archivo AASA como parte de la misma lista de verificación previa al envío, no como algo añadido después de que la app ya esté en la tienda.

Errores comunes

La mayoría de los fallos de enlaces universales se reducen a una de cinco causas, todas documentadas en la guía de resolución de problemas de Apple:

• Una redirección en la respuesta del AASA o de assetlinks.json. Cualquier 3xx en esa cadena rompe la validación en ambas plataformas.
• Un desajuste de dominio. La capacidad Associated Domains de la app debe referenciar exactamente el dominio que alberga el archivo AASA, no un subdominio o un alias de él.
• Un certificado caducado. Si el archivo AASA está firmado, un certificado de firma o intermedio caducado lo invalida incluso cuando el contenido JSON es correcto.
• Un desajuste de appID o de ruta. El appID del archivo AASA debe coincidir con el App ID real de la app, y al menos una entrada de ruta debe coincidir con la ruta del enlace tocado.
• Un delegado que rechaza el enlace. El método propio de UIApplicationDelegate de la app puede devolver false y negarse a manejar un enlace que, por lo demás, validó correctamente.

Un identificador desajustado, una credencial caducada, una configuración que el proceso de revisión no saca a la luz hasta el envío: estas mismas categorías aparecen una y otra vez, en general, en los motivos de rechazo del App Store. Probar el traspaso en un dispositivo real, con la app instalada y recién eliminada, antes del envío resuelve la mayoría de estos casos. Los equipos que planean una app nativa que necesite un traspaso limpio desde la web pueden ver cómo encaja esto en una compilación de iOS más amplia en los servicios de desarrollo iOS de Kallos Labs.

Preguntas frecuentes

¿Los enlaces universales funcionan si la app no está instalada?

Sí. Un enlace universal tocado recurre a abrir la misma URL en Safari, o en Chrome para los App Links de Android, cuando la app no está en el dispositivo, lo que hace que el mecanismo sea seguro de publicar sin crear el riesgo de un enlace roto.

¿Por qué mi enlace universal no abre la app aunque el archivo AASA valide correctamente?

Un archivo AASA válido es necesario pero no suficiente. La propia guía de resolución de problemas de Apple señala un certificado de firma caducado, un appID en el archivo que no coincide con el App ID real de la app, ninguna ruta declarada que coincida con la ruta del enlace tocado, y el método delegado de la app devolviendo false y rechazando el enlace, como las causas más comunes una vez que la validación en sí ya pasó.

¿Necesito tanto un archivo AASA como un archivo assetlinks.json?

Sí, si el producto se publica en ambas plataformas. Apple lee apple-app-site-association para los enlaces universales, y Android lee assetlinks.json para los App Links. Son archivos separados, con esquemas separados, alojados en rutas well-known separadas, y cada uno debe pasar de forma independiente las reglas de alojamiento de HTTPS sin redirecciones.

¿Cuál es la diferencia entre un enlace universal y un esquema de URL personalizado?

Un esquema de URL personalizado como myapp:// puede registrarlo más de una app y no tiene ninguna prueba de propiedad, así que ni iOS ni Android pueden verificar qué app debería manejarlo. Un enlace universal o un App Link de Android usa una URL https:// real, atada a un dominio cuya propiedad la empresa demuestra mediante el archivo AASA o assetlinks.json, de modo que el sistema operativo puede abrir la app de forma segura sin un cuadro de diálogo de desambiguación.

¿La página alternativa debe redirigir de inmediato a la app, o mostrar algo primero?

Sé propietario de la URL de destino e intenta el traspaso primero. Si la app no responde, mantén al visitante en esa misma página con un aviso claro para instalarla, en lugar de redirigirlo otra vez o mostrarle un enlace roto, que es el patrón que describe la propia documentación de Google sobre enlaces profundos.