Enlaces Universales de iOS

Dominios asociados, apple-app-site-association y hospedaje en CDN - la guía de iOS para abrir URLs https:// de marketing directamente en tu app Expo SDK 57 sin un diálogo de desambiguación de esquema personalizado.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

// app.config.ts
export default {
  expo: {
    scheme: "shopapp",
    ios: {
      bundleIdentifier: "com.example.shopapp",
      associatedDomains: ["applinks:shop.example.com"],
    },
  },
};

// https://shop.example.com/.well-known/apple-app-site-association
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.example.shopapp",
        "paths": ["/orders/*", "/product/*", "/invite/*"]
      }
    ]
  }
}

Cuándo usarlo:

• Las campañas de correo electrónico y SMS usan enlaces https:// que deberían abrir la app cuando está instalada.
• Quieres una transición sin interrupciones desde tu sitio de marketing sin prompts myapp://.
• Los listados de App Store y smart banners hacen referencia a las mismas URLs canónicas que la app.
• Necesitas que iOS verifique la propiedad del dominio antes de abrir enlaces en la app.

Ejemplo Funcionando

Configuración de extremo a extremo para https://shop.example.com/orders/* en una app Expo con prebuild.

Paso 1 - Derechos a través de app.config.ts

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  scheme: "shopapp",
  ios: {
    bundleIdentifier: "com.example.shopapp",
    associatedDomains: ["applinks:shop.example.com"],
  },
  android: {
    package: "com.example.shopapp",
  },
};
 
export default config;

Paso 2 - Hospeda AASA en tu CDN

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.shopapp",
        "paths": [
          "/orders/*",
          "/product/*",
          "NOT /admin/*",
          "NOT /api/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.shopapp"]
  }
}

Sirve en ambas rutas (Apple revisa una u otra):

• https://shop.example.com/apple-app-site-association
• https://shop.example.com/.well-known/apple-app-site-association

Paso 3 - Encabezados de respuesta de CDN

Content-Type: application/json
Cache-Control: max-age=3600

• Sin redirecciones 301/302 en la URL de AASA - Apple rechaza archivos de asociación redirigidos.
• El archivo debe estar sin firmar - no se requiere extensión .json; cuerpo JSON sin procesar.
• Reemplaza ABCDE12345 con tu Team ID de Apple del portal de desarrolladores.

Paso 4 - Pantalla de Expo Router

// app/orders/[id].tsx
import { useLocalSearchParams } from "expo-router";
import { Text, View } from "react-native";
 
export default function OrderScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return (
    <View style={{ padding: 16 }}>
      <Text>Order {id}</Text>
    </View>
  );
}

Paso 5 - Construye y verifica

npx expo prebuild --platform ios
npx expo run:ios
# Simulador: abre el enlace universal
xcrun simctl openurl booted "https://shop.example.com/orders/42"

Lo que esto demuestra:

• El derecho associatedDomains se genera en prebuild.
• Reglas de ruta AASA que limitan qué URLs abren la app.
• Encabezados de CDN requeridos para el rastreador de Apple.
• Coincidencia de ruta dinámica de Expo Router /orders/42.
• Pruebas en Simulador antes de TestFlight.

Análisis Profundo

Cómo Funciona

• En la instalación, iOS obtiene AASA de cada dominio applinks: en tus derechos.
• Apple almacena datos de asociación en caché en el dispositivo - las actualizaciones se propagan lentamente (horas, a veces días).
• Cuando el usuario toca un enlace https:// coincidente, iOS abre tu app y pasa la URL a React Native.
• Si la verificación falla o la ruta está excluida, Safari maneja la URL normalmente.
• Los esquemas personalizados siguen funcionando en paralelo - los enlaces universales se prefieren para marketing.

Reglas de Ruta AASA

Lista de Verificación de CDN

Notas de iOS

# Valida AASA con el CDN de Apple (el dispositivo eventualmente verá los mismos datos)
curl -s "https://app-site-association.cdn-apple.com/a/v1/shop.example.com" | jq .

• Después de cambiar AASA, aumenta el caché de CDN o purga los nodos de borde - los archivos antiguos causan "funciona en staging, roto en prod".
• Los builds de TestFlight usan el Bundle ID de producción - coincide con appID exactamente.
• Los usuarios que eligieron "Abrir en Safari" deshabilitan los enlaces universales por sitio hasta que se restablezcan en Configuración.

Errores Comunes

• Team ID incorrecto en appID - el enlace abre Safari silenciosamente. Solución: TEAMID.bundleIdentifier de Apple Developer - Membership.
• AASA detrás de redirección - redirección www a apex rompe la obtención. Solución: sirve AASA en el host exacto en associatedDomains.
• Olvidar reconstruir después de agregar associatedDomains - derecho faltante en IPA. Solución: eas build --platform ios después del cambio de configuración.
• Incluir /api/* en rutas - Las respuestas JSON de API no deberían abrir la app. Solución: reglas NOT explícitas o prefijos más estrechos.
• Esperar actualizaciones instantáneas de AASA - iOS almacena en caché agresivamente. Solución: cambia rutas solo con campañas de marketing versionadas; mantén rutas antiguas durante la transición.
• Enlace universal desde el mismo dominio en WKWebView - el navegador en la app puede no entregar. Solución: usa SFSafariViewController o <a target="_blank"> para abrir externamente.

Alternativas

FAQs

Relacionado

• Conceptos Básicos de Enlace Profundo - descripción general de esquema vs HTTPS
• API expo-linking - patrones de análisis y listener
• App Links de Android - verificación paralela de Android
• Matriz de Prueba de Enlace Profundo - matriz de simulador y dispositivo de iOS
• ../expo-router/expo-router-basics/expo-router-basics.md - diseño de archivo de ruta
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - reglas de revisión de enlace profundo

Versiones de stack: Esta página se escribió para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).