📆 ⏱️ 6 min de lectura

Vamos a empezar por el principio: ¿Qué es un Universal Link?

Un Universal Link es una forma de conectar URLs web directamente con tu app iOS. Cuando un usuario toca un enlace que apunta a tu dominio (por ejemplo, desde un mensaje, un email o cualquier otra app), iOS puede abrir directamente tu app en lugar de Safari, creando una experiencia de usuario mucho más fluida y nativa.

Es como tener deep linking, pero mejor: funciona desde cualquier lugar del sistema y no requiere que el usuario confirme nada.

Los Universal Links funcionan mediante un archivo especial que Apple busca en tu servidor web: el archivo apple-app-site-association. Este archivo le dice a iOS qué URLs de tu dominio deben abrir tu app.

El archivo apple-app-site-association (AASA)

El archivo apple-app-site-association es un archivo JSON que mapea las URLs de tu dominio que quieres que abran tu app iOS. Es decir, le estás diciendo a iOS: “cuando un usuario toque un enlace que empiece por /test, por ejemplo, abre mi app en lugar de Safari”.

Ejemplo práctico: Si configuras en el archivo que todas las URLs que empiecen por /test abran la app, entonces:

  • ✅ https://tudominio.com/test/producto-123 → Abre tu app
  • ✅ https://tudominio.com/test/usuario/456 → Abre tu app
  • ❌ https://tudominio.com/otra-ruta → Se abre en Safari (no está mapeada)

Importante: El archivo apple-app-site-association solo define qué URLs abren la app. Una vez que la app se abre con un Universal Link, cómo la app gestione qué hacer con esa URL es un tema completamente separado y agnóstico a este problema de configuración. La app recibirá la URL y tú decides cómo manejarla en tu código Swift.

⚠️ El archivo es completamente público: Este archivo debe ser accesible públicamente en tu servidor. No contiene información sensible, solo mapea qué URLs de tu dominio deben abrir tu app. Cualquiera puede acceder a él desde un navegador.

Ubicación del archivo

Apple permite dos ubicaciones para el archivo:

  1. En la raíz del dominio: https://tudominio.com/apple-app-site-association
  2. En .well-known: https://tudominio.com/.well-known/apple-app-site-association

Recomendación: Usa siempre .well-known porque:

  • Es el estándar web (RFC 8615)
  • Funciona por igual en producción y en entornos de pruebas
  • Mantiene los archivos organizados
  • Evita conflictos con rutas de tu aplicación

El CDN de Apple

Cuando Apple detecta tu archivo apple-app-site-association en un dominio público, lo descarga y lo guarda en su propio CDN (Content Delivery Network). Esto significa que:

  1. Apple accede al archivo primero: iOS intenta obtener el archivo desde el CDN de Apple antes que desde tu servidor, lo que hace que sea muy rápido
  2. Funciona en producción: En dominios públicos accesibles, Apple puede descargarlo y cachearlo correctamente
  3. Problemas en entornos privados: Si tu dominio está detrás de una VPN o en un entorno privado, los servidores de Apple no pueden acceder al archivo, por lo que no pueden guardarlo en su CDN. Por eso en entornos de pruebas necesitas usar el modo developer (te lo explico en el siguiente artículo)

Estructura del archivo

El archivo debe ser JSON válido y tener esta estructura básica:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAM_ID.com.tuempresa.tuapp"],
        "components": [
          {
            "/": "/test/*",
            "comment": "Matches any URL with path that starts with /test/"
          }
        ]
      }
    ]
  }
}

Elementos importantes:

  • TEAM_ID: Tu Team ID de Apple Developer
  • com.tuempresa.tuapp: Tu Bundle Identifier exacto
  • components: Mapea las URLs que quieres que abran tu app. En el ejemplo, "/": "/test/*" significa que todas las URLs que empiecen por /test abrirán tu app.

⚠️ Crítico: El archivo NO debe tener extensión .json - debe llamarse exactamente apple-app-site-association

¿Qué necesitas para que funcionen?

Para que los Universal Links funcionen, necesitas dos cosas:

  1. El archivo apple-app-site-association en tu servidor web que mapea las URLs
  2. Configurar Associated Domains en Xcode para decirle a iOS que tu app puede manejar enlaces de tu dominio.

Associated Domains es una capability de iOS que le dice al sistema qué dominios puede manejar tu app. Sin esta configuración, iOS no sabrá que tu app puede abrir enlaces de tu dominio. En Signing & Capabilities, añade en Associeated Domains:

applinks:tudominio.com

Safari tiene comportamiento especial

Safari tiene un comportamiento especial con Universal Links:

  • Enlaces del mismo dominio: Si tocas un Universal Link dentro de Safari que apunta al mismo dominio que la página actual, iOS mantiene el contexto de navegación y abre el enlace en Safari. Apple asume que si estás navegando en Safari, quieres continuar en el navegador.

  • Enlaces de dominio diferente: Si el Universal Link apunta a un dominio diferente, iOS sí abrirá tu app (si está instalada).

  • Copiar y pegar URLs: Si copias una URL y la pegas en la barra de direcciones de Safari, Apple interpreta que tu intención es continuar navegando en el navegador, no abrir la app.

Chrome como navegador por defecto (iOS 14+)

Desde iOS 14, Apple permite configurar navegadores de terceros (como Chrome, Firefox, Edge, etc.) como navegador por defecto. Sin embargo, los Universal Links están principalmente soportados por Safari. Si Chrome (u otro navegador) está configurado como predeterminado, los Universal Links pueden no funcionar automáticamente.

Resumen

Los Universal Links son una forma poderosa de conectar tu app iOS con URLs web. Ventajas de los Universal Links:

  • ✅ Funcionan desde cualquier app del sistema (Messages, Mail, WhatsApp, etc.)
  • ✅ No requieren confirmación del usuario
  • ✅ Si la app no está instalada, el enlace se abre en Safari
  • ✅ Mejoran significativamente la experiencia de usuario

Limitaciones a tener en cuenta:

  • ⚠️ Safari tiene comportamiento especial: mantiene el contexto de navegación para enlaces del mismo dominio
  • ⚠️ Los navegadores de terceros (Chrome, Firefox, etc.) pueden no soportarlos completamente cuando están configurados como predeterminados

Recursos útiles

  • 📹 Video oficial de Apple: What’s New in Universal Links (WWDC 2020) - Sesión completa donde Apple explica los Universal Links
  • 🔍 Well-Known.dev: Herramienta para buscar y verificar archivos .well-known/ en sitios web, incluyendo apple-app-site-association. Te permite ver los associated domains de cualquier página y verificar que tu configuración esté correcta
  • 📚 Documentación oficial: Supporting Universal Links - Documentación completa de Apple

En el siguiente artículo te explico cómo testearlos en entornos de pruebas, que es donde suelen aparecer la mayoría de los problemas.

Nos leemos 🫶