Derechos y capacidades

Push, dominios asociados, keychain y modos de fondo - configurar los derechos de iOS a través de app.config.ts y complementos de configuración para que Expo prebuild escriba el archivo .entitlements correcto antes de EAS Build o TestFlight.

Receta

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

// app.config.ts - derechos comunes a través de la configuración de Expo
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  ios: {
    bundleIdentifier: "com.example.shopapp",
    // Enlaces universales
    associatedDomains: ["applinks:shop.example.com"],
    // Grupo de acceso a keychain (opcional - Secure Store)
    entitlements: {
      "keychain-access-groups": ["$(AppIdentifierPrefix)com.example.shopapp.shared"],
    },
    infoPlist: {
      UIBackgroundModes: ["remote-notification"],
    },
  },
  plugins: [
    "expo-router",
    [
      "expo-notifications",
      {
        icon: "./assets/notification-icon.png",
        color: "#ffffff",
        sounds: ["./assets/notification.wav"],
      },
    ],
  ],
};
 
export default config;

Cuándo usarlo:

• Agregar notificaciones push o enlaces universales a un agrupamiento de producción.
• Compartir tokens entre app y extensión de widget a través de keychain / grupos de aplicaciones.
• Habilitar búsqueda de fondo, procesamiento o remote-notification para push silencioso.
• App Review rechaza con "missing entitlement" o "background modes without justification."
• Migrar derechos desde pestañas de Xcode editadas manualmente a configuración compatible con CNG.

Ejemplo funcional

Notificaciones push

Paso 1 - Complemento + cadenas de permisos

// app.config.ts
export default {
  expo: {
    plugins: ["expo-notifications"],
    ios: {
      infoPlist: {
        UIBackgroundModes: ["remote-notification"],
      },
    },
  },
};

Paso 2 - Portal de desarrollador de Apple

1. Identifiers → tu App ID → habilita Push Notifications.
2. Keys → crea una clave APNs (.p8) - cárgala en EAS o tu proveedor de push.
3. Credenciales de EAS: eas credentials → iOS → Push Key.

Paso 3 - Reconstruye y prueba en el dispositivo

npx expo prebuild --platform ios
eas build --profile development --platform ios
# Push no se entrega a simuladores - usa un dispositivo USB

// app/_layout.tsx (fragmento)
import * as Notifications from "expo-notifications";
 
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
    shouldShowList: true,
  }),
});

Dominios asociados (Enlaces universales)

ios: {
  associatedDomains: [
    "applinks:shop.example.com",
    "webcredentials:shop.example.com", // Autocompletado de contraseña (opcional)
  ],
},

• Aloja apple-app-site-association en el dominio - ver iOS Universal Links.
• El prefijo debe ser applinks: - no nombres de host sin prefijo.
• Reconstruye después de los cambios - OTA no puede agregar dominios asociados.

xcrun simctl openurl booted "https://shop.example.com/orders/42"

Keychain y grupos de aplicaciones

ios: {
  entitlements: {
    "keychain-access-groups": [
      "$(AppIdentifierPrefix)com.example.shopapp.shared",
    ],
    "com.apple.security.application-groups": [
      "group.com.example.shopapp",
    ],
  },
},

import * as SecureStore from "expo-secure-store";
 
await SecureStore.setItemAsync("refresh_token", token, {
  keychainAccessible: SecureStore.WHEN_UNLOCKED,
  // accessGroup: "group.com.example.shopapp", // cuando la extensión debe leer el mismo secreto
});

• Los identificadores de grupos de aplicaciones deben coincidir entre la app principal y las extensiones (widgets).
• El compartir de keychain requiere un grupo de acceso idéntico en los derechos de ambos destinos.

Modos de fondo

plugins: [
  "expo-background-task", // agrega processing + BGTaskSchedulerPermittedIdentifiers
],

Lo que esto demuestra:

• Los derechos fluyen desde la configuración → .entitlements en prebuild.
• Push requiere portal + reconstrucción binaria + prueba en dispositivo.
• Los dominios asociados se emparejan con archivos AASA alojados.
• Los modos de fondo deben reflejar caminos de código reales - no copiar y pegar de Stack Overflow.

Profundización

Qué son los derechos

Los derechos son pares clave-valor en YourApp.entitlements que el código de Apple firma en la IPA. Controlan APIs:

<!-- Fragmento generado - no editar manualmente bajo CNG -->
<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:shop.example.com</string>
</array>
<key>aps-environment</key>
<string>development</string> <!-- production en compilaciones de App Store -->

Push de desarrollo vs producción

EAS establece esto desde el perfil de distribución. Síntomas de desajuste: el token se registra pero las notificaciones nunca llegan.

Complementos de configuración vs ios.entitlements

// Prefiere campos de configuración de alto nivel cuando Expo los documenta
ios: { associatedDomains: ["applinks:example.com"] }
 
// Usa ios.entitlements para claves sin campos de primera clase
ios: {
  entitlements: {
    "com.apple.developer.networking.networkextension": ["app-proxy-provider"],
  },
}
 
// O un complemento de configuración local con withEntitlementsPlist

Ver Config Plugins - withEntitlementsPlist es la salida de emergencia.

Verificar derechos en una IPA compilada

# Después de eas build --local o Xcode Archive
unzip -q ShopApp.ipa -d /tmp/shop
codesign -d --entitlements :- /tmp/shop/Payload/ShopApp.app > /tmp/entitlements.plist
/usr/libexec/PlistBuddy -c Print /tmp/entitlements.plist

Compara la salida con app.config.ts antes de culpar al código de la aplicación.

Errores comunes

• Editar Signing & Capabilities en Xcode bajo CNG - se sobrescribe en prebuild. Solución: solo app.config.ts.
• Falta el prefijo applinks: - el dominio asociado se ignora silenciosamente. Solución: applinks:host.example.com.
• Esperar que OTA agregue push o dominios - los derechos son nativos. Solución: nuevo eas build.
• UIBackgroundModes sin implementación - rechazo de Directriz 2.5.4. Solución: elimina los modos no utilizados.
• Expo Go para control de calidad de enlace universal - ID de agrupamiento incorrecto. Solución: cliente dev con tu bundleIdentifier.
• El widget lee keychain pero sin grupo de aplicaciones - la extensión no puede ver datos de la app principal. Solución: identificadores group. coincidentes - ver App Extensions & Widgets.

Alternativas

Preguntas frecuentes

Relacionado

• iOS Universal Links - alojamiento y verificación de AASA
• Push Notification Deep Links - tocar - enrutamiento de hilos
• App Extensions & Widgets - grupos de aplicaciones y derechos de extensión
• Config Plugins - withEntitlementsPlist
• iOS Credentials & Provisioning - claves y perfiles de APNs
• Background Sync & TaskManager - modo de fondo processing

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).