Universal Links iOS: apple-app-site-association (AASA) paso a paso
Cómo configurar Universal Links en iOS: archivo apple-app-site-association (AASA), Associated Domains en Xcode, manejo del enlace en la app, pruebas, CDN de Apple y checklist cuando no funcionan.

Los Universal Links iOS son enlaces https normales de tu sitio web que, si la app está instalada, se abren directamente en ella en lugar de pasar por el navegador. Para que funcionen necesitas dos piezas que se validan entre sí: el archivo apple-app-site-association (AASA) en tu dominio y la capability Associated Domains en tu app. Si alguna de las dos no coincide, iOS abre el enlace en Safari sin avisarte. Esta guía ES-CO es la contraparte de nuestra guía de App Links Android: mismo objetivo, protocolo distinto.
Qué son los Universal Links (y en qué se diferencian de un deep link)
Según la documentación de Apple, cuando alguien toca un universal link el sistema lleva el enlace directo a tu app, sin pasar por el navegador predeterminado ni por tu web. Como son URLs HTTP/HTTPS estándar, una misma URL sirve para la web y para la app: si la persona no tiene la app instalada, se abre en su navegador y tu sitio responde como siempre.
Un deep link con esquema propio (miapp://producto/123) también abre la app, pero no verifica que el dominio sea tuyo y no tiene respaldo web si la app no está instalada. Con universal links, al instalar la app el sistema comprueba un archivo en tu servidor que solo tú puedes publicar. Esa asociación en dos sentidos es la que impide que otra app "se robe" tus enlaces.
Lo que necesitas antes de empezar:
- Un dominio propio servido por HTTPS con certificado válido.
- Tu App ID: prefijo del equipo (normalmente el Team ID) + Bundle ID de tu app iOS, por ejemplo
ABCDE12345.com.ejemplo.miapp. - Acceso a Xcode (o a la configuración nativa que genere tu framework).
Paso 1: crear el archivo apple-app-site-association (AASA)
Crea un archivo llamado exactamente apple-app-site-association, sin extensión .json. Para universal links, el contenido va dentro de la clave applinks. Este es un ejemplo genérico con el formato actual que documenta Apple (appIDs + components):
{
"applinks": {
"details": [
{
"appIDs": ["ABCDE12345.com.ejemplo.miapp"],
"components": [
{ "/": "/producto/*", "comment": "Fichas de producto" },
{ "/": "/ayuda/web/*", "exclude": true, "comment": "Se queda en la web" },
{ "#": "no_universal_links", "exclude": true }
]
}
]
}
}
Cómo leerlo:
appIDs: lista de apps que pueden abrir enlaces del dominio, con el formato<Application Identifier Prefix>.<Bundle Identifier>.components: reglas de coincidencia sobre partes de la URL."/"evalúa el path,"?"los parámetros de query y"#"el fragmento.exclude: true: la URL que coincide no se abre como universal link. El orden importa: pon las exclusiones antes de reglas más generales que también las cubrirían.comment: solo documentación; el sistema no lo usa.
Existe un formato antiguo con appID (texto) y paths (array, con NOT para excluir). Apple pide no mezclar ambos formatos en el mismo archivo, porque puede causar comportamientos inesperados. Si heredaste un AASA viejo, migra todo de una vez.
Paso 2: publicar el AASA en tu dominio
La URL del archivo debe seguir este formato:
https://<dominio completo>/.well-known/apple-app-site-association
Reglas que conviene tener en cuenta:
- HTTPS con certificado válido y sin redirects. Un 301 o 302 hacia otro host o path rompe la verificación.
- Un archivo por subdominio. Si usas
example.com,www.example.comyapp.example.com, cada uno necesita su entrada en el entitlement y su propio AASA. Si declaras un comodín*.example.com, el archivo va en el dominio raíz (https://example.com/.well-known/...), y eso no cubre una entrada específica comoapplinks:www.example.com. - Acceso público. Un 403 o 404 desde cualquier IP o país bloquea a la CDN de Apple. Revisa firewalls, reglas anti-bots y protección por geolocalización; el servidor debe aceptar cualquier User-Agent.
- Sírvelo como JSON (
application/jsones lo habitual) y valida que el contenido sea JSON correcto.
Prueba rápida desde tu terminal:
curl -v https://tudominio.com/.well-known/apple-app-site-association
curl -A "MiAgente-Bot/1.0" https://tudominio.com/.well-known/apple-app-site-association
En el primer comando busca un 200 sin redirects; el segundo comprueba que tu servidor no rechace User-Agents desconocidos.
Paso 3: agregar Associated Domains en Xcode
En Xcode abre tu target → Signing & Capabilities → + Capability → Associated Domains. Esto añade el entitlement a la app y la funcionalidad al App ID. Luego agrega cada dominio con el formato:
applinks:tudominio.com
Errores típicos aquí:
- Escribir
https://o una ruta: solo va el dominio completo, sin path, query ni/final. - Poner un puerto (
applinks:example.com:8080): no funciona. - Declarar
www.tudominio.compero publicar el AASA solo entudominio.com(o al revés).
Con Expo / React Native el equivalente es configurar ios.associatedDomains en la config de la app; en Flutter editas el target Runner en Xcode igual que en una app nativa. El framework no reemplaza la verificación: solo te entrega la URL cuando iOS ya decidió abrir la app.
Paso 4: manejar el enlace dentro de la app
Cuando iOS abre tu app desde un universal link, la app recibe un NSUserActivity de tipo NSUserActivityTypeBrowsingWeb con la URL en webpageURL. En UIKit lo recibes en application(_:continue:restorationHandler:); si usas escenas, en los métodos del UISceneDelegate; en SwiftUI puedes usar onOpenURL. Apple recomienda validar todos los parámetros, descartar URLs mal formadas y no permitir acciones sensibles (como borrar contenido) directamente desde un enlace.
Paso 5: probar y depurar Universal Links iOS
Prueba manual: pega el enlace en Notas y mantén presionado. Si está bien configurado, verás la opción de abrir en tu app además del navegador. Ojo: escribir la URL en la barra de Safari nunca abre la app, y tocar un enlace del mismo dominio mientras navegas en Safari mantiene a la persona en el navegador.
Diagnóstico en el iPhone: activa el modo de desarrollador, entra a Ajustes → Desarrollador, activa Associated Domains Development y usa Diagnostics con tu URL completa.
En un Mac: sudo swcutil dl -d tudominio.com comprueba la descarga del AASA y sudo swcutil verify valida el JSON contra una URL concreta.
La CDN de Apple: desde iOS 14, los dispositivos no piden el AASA directamente a tu servidor sino a una CDN de Apple. La documentación indica que la CDN pide el archivo de tu dominio dentro de las 24 horas, y que los dispositivos buscan actualizaciones aproximadamente una vez por semana tras la instalación. No hay forma de invalidar la caché: para forzar el archivo nuevo, reinstala la app. En desarrollo puedes usar applinks:tudominio.com?mode=developer para saltarte la CDN (solo con apps firmadas con perfil de desarrollo y en dispositivos que lo activen).
Instala las builds de prueba desde Xcode o TestFlight, y antes de enviar a revisión repasa tu checklist para publicar en App Store.
Universal links iOS not working: checklist rápida
- ¿El AASA responde
200en/.well-known/apple-app-site-association, sin redirects ni extensión? - ¿El
appIDscoincide con Team ID + Bundle ID de la build instalada (ojo si transferiste la app o cambiaste de equipo)? - ¿El dominio del entitlement es idéntico al host del archivo (con o sin
www)? - ¿Algún
componentsconexcludeestá atrapando la ruta que pruebas? - ¿Mezclaste formato antiguo (
paths) y nuevo (components)? - ¿Tu firewall o CDN bloquea IPs o User-Agents desconocidos?
- ¿Pruebas tecleando la URL en Safari o desde una página del mismo dominio? Esos casos no abren la app por diseño.
- ¿Cambiaste el AASA hace poco? Puede seguir la versión en caché; reinstala o usa
mode=developer. - ¿Pruebas en otro navegador? Según Apple, depende de cada navegador habilitar universal links; Safari los implementa completos.
Universal Links iOS vs App Links Android
La idea es la misma, pero los archivos no son intercambiables. En Android publicas assetlinks.json con el package y el SHA-256 del certificado de firma; en iOS publicas el AASA con Team ID + Bundle ID y reglas de path. Si tu app es multiplataforma, mantén ambos archivos en .well-known y revísalos cuando cambies dominio, equipo o firma. Todo el detalle de Android está en la guía de App Links Android.
Preguntas frecuentes
¿Dónde va el archivo apple-app-site-association?
En https://tudominio.com/.well-known/apple-app-site-association, sin extensión, por HTTPS con certificado válido y sin redirects. Cada subdominio declarado necesita su propio archivo.
¿El AASA lleva extensión .json?
No. El nombre es apple-app-site-association sin extensión, aunque el contenido sea JSON.
¿Por qué mis universal links abren Safari y no la app?
Lo más común: appIDs incorrecto, dominio del entitlement distinto al del archivo, redirects o bloqueos en el servidor, una regla exclude, o que estés probando desde la barra de Safari o desde el mismo dominio.
¿Cuánto tarda en actualizarse el AASA?
Según Apple, la CDN pide el archivo dentro de las 24 horas y los dispositivos revisan actualizaciones aproximadamente cada semana. Para probar cambios rápido, reinstala la app o usa ?mode=developer.
¿Funcionan universal links en el simulador?
Para validar de verdad, prueba en un dispositivo con la build instalada desde Xcode o TestFlight y usa el diagnóstico de Ajustes → Desarrollador. Con un servidor privado o de pruebas, usa mode=developer.
¿Universal links y App Links son lo mismo?
Son equivalentes en concepto (enlaces HTTPS verificados por dominio), pero iOS usa AASA + Associated Domains y Android usa assetlinks.json + autoVerify.
Con los enlaces funcionando, el resto del lanzamiento es trabajo de tienda: ficha, capturas, política de privacidad y revisión. Prueba AppConsol: crea tu cuenta gratis y prepara todo eso en un solo lugar antes de enviar tu app iOS a revisión.
Sigue aprendiendo

1 de noviembre de 2026
Bundle ID en iOS: qué es, cómo crearlo en App Store Connect y errores comunes

22 de octubre de 2026
Generar IPA en Xcode: cómo exportar tu app iOS paso a paso

15 de noviembre de 2026
Icon Composer: cómo crear el ícono Liquid Glass de tu app

7 de noviembre de 2026
App Links Android: assetlinks.json, verificación y fallos comunes

28 de octubre de 2026
Privacy manifest en iOS: cómo crear PrivacyInfo.xcprivacy y corregir ITMS-91053 e ITMS-91061