📆 ⏱️ 5 min de lectura

Si ya sabes qué son los Universal Links (si no, te recomiendo leer este artículo primero), el siguiente paso es conseguir que funcionen en entornos de pruebas. Y es que puede ser un auténtico dolor de cabeza.

Si has intentado configurar Universal Links y no te funcionan en preproducción, preview o similar, probablemente es por alguno de estos puntos:

  1. Ubicación incorrecta del archivo apple-app-site-association
  2. Configuración incorrecta de Associated Domains en Xcode
  3. No usar el modo developer para testing
  4. Intentar probarlos desde Safari (comportamiento especial de Apple)
  5. Tener Chrome u otro navegador como predeterminado (iOS 14+)

📁 1. Ubicación incorrecta del archivo apple-app-site-association

El problema de colocar el archivo en la raíz de nuestro proyecto, es que en entornos de pruebas, habitualmente privados o tras una VPN, Apple no tiene acceso a la ruta de ese fichero en concreto, por lo que no funcionará.

¿Por qué pasa esto?

En producción, Apple guarda el archivo en su propio CDN y accede a él como primera opción. Pero en entornos de pruebas privados o tras una VPN, los servidores de Apple no pueden acceder a tu dominio, por lo que no pueden descargarlo y guardarlo en su CDN.

Ten en cuenta que apple guarda esta informacion en su CDN cuando instalas la app, si cambias algo necesitas borrarla y volverla a instalar porque si no utlilizará la version cacheada que ya tiene.

Solución: Coloca el archivo dentro de .well-known/

# Correcto ✅
.well-known/apple-app-site-association

# Incorrecto ❌
.well-known/apple-app-site-association.json
.well-known/apple-app-site-association.txt

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

Usar .well-known te asegura que funcionará por igual tanto en producción como en preview/preproducción.

💡 Curiosidad: Si ahora mismo no se peude hacer el cambio de ruta del archivo, o debes esperar para que se haga efectivo, puedes usar Charles Proxy o Proxyman para interceptar la llamada y servir tu propio archivo. Puedes ver más detalles en esta discusión de Stack Overflow. Aunque he de decir, que yo no conseguí hacerlo funcionar, pero es que yo y los proxys no nos llevamos muy bien. 😅

⚙️ 2. Configuración incorrecta de Associated Domains en Xcode

En Xcode, necesitas configurar correctamente los Associated Domains en las capabilities de tu app.

Pasos a seguir:

  1. Abre tu proyecto en Xcode
  2. Selecciona tu target → Signing & Capabilities
  3. Haz clic en + Capability y añade Associated Domains
  4. Añade tu dominio con el formato: applinks:tu-dominio.com con el modo desarrollo al final ?mode=developer
applinks.mi-app.com?mode=developer

⚠️ Importante:

  • NO incluyas https:// ni http://
  • NO incluyas la ruta / al final

🔧 3. No usar el modo developer para testing

  1. Conecta tu dispositivo iOS a tu Mac
  2. Abre Xcode y ve a Window → Devices and Simulators
  3. Selecciona tu dispositivo
  4. En tu dispositivo iOS, ve a Ajustes → General → Gestión de VPN y Dispositivos
  5. Toca tu perfil de desarrollador y confía en él
  6. Ve a Ajustes → Desarrollador (solo aparece después de conectar a Xcode)
  7. Activa Associated Domains Development

⚠️ Crítico: Sin este modo activado, iOS no verificará los Universal Links en entornos de desarrollo, aunque todo esté configurado correctamente.

🚨 4. Intentar probarlos desde Safari

Este es uno de los errores más comunes. Safari tiene un comportamiento especial con los Universal Links que puede hacer que no funcionen como esperas.

¿Por qué pasa esto?

Safari tiene su propia lógica para manejar los Universal Links. Cuando haces clic en un link dentro de Safari, puede que te abra la página web en lugar de la app, incluso si la app está instalada y configurada correctamente.

Solución: Usa otras apps para probar los Universal Links, como Notas, por ejemplo.

🌐 5. Tener Chrome u otro navegador como predeterminado (iOS 14+)

Desde iOS 14, Apple cambió el comportamiento de los Universal Links cuando tienes un navegador diferente a Safari como predeterminado.

¿Qué pasa?

Si tienes Chrome, Firefox u otro navegador como predeterminado, iOS puede no abrir la app cuando haces clic en un Universal Link, incluso si está correctamente configurado. Esto, que yo sepa, no tiene solucion, mas que la de usar Safari como navegador por defecto.

Reflexión final

Los Universal Links en entornos de pruebas requieren configuración específica que difiere de producción. Los puntos clave para recordar:

Key points:

  • Olvida el simulador, solo funciona en dispositivos iOS reales.
  • El archivo debe estar en .well-known/ - no en la raíz del dominio
  • Las opciones de desarrollador solo aparecen después de conectar el dispositivo a Xcode
  • Debes activar “Associated Domains Development” en los ajustes del dispositivo
  • Solo funciona en desarrollo con certificados de desarrollo + modo developer
  • NO uses Safari para testing - usa Messages, Notes, Mail, etc.
  • Safari debe ser el navegador por defecto
  • La configuración se cachea - reinstala la app tras cambios

¿Has tenido problemas configurando Universal Links en entornos de pruebas? ¡Me encantaría conocer tu experiencia!

Nos leemos 🫶

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