Entitlements & Capabilities

Push, domínios associados, keychain e modos de background - configurando entitlements do iOS através de app.config.ts e plugins de configuração para que o Expo prebuild escreva o arquivo .entitlements correto antes do EAS Build ou TestFlight.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// app.config.ts - entitlements comuns via configuração Expo
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "ShopApp",
  slug: "shop-app",
  ios: {
    bundleIdentifier: "com.example.shopapp",
    // Universal Links
    associatedDomains: ["applinks:shop.example.com"],
    // Grupo de acesso do 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;

Quando usar isto:

• Adicionando notificações push ou links universais a um bundle de produção.
• Compartilhando tokens entre o app e a extensão de widget via keychain / app groups.
• Habilitando background fetch, processamento ou remote-notification para push silencioso.
• App Review rejeita com "entitlement ausente" ou "modos de background sem justificativa."
• Migrando entitlements de abas editadas manualmente no Xcode para configuração compatível com CNG.

Exemplo de Trabalho

Notificações push

Passo 1 - Plugin + strings de permissão

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

Passo 2 - Portal do Desenvolvedor Apple

1. Identifiers → seu App ID → habilite Push Notifications.
2. Keys → crie a chave APNs (.p8) - faça upload para o EAS ou seu provedor de push.
3. Credenciais EAS: eas credentials → iOS → Push Key.

Passo 3 - Reconstrua e teste no dispositivo

npx expo prebuild --platform ios
eas build --profile development --platform ios
# Push não entrega para simuladores - use dispositivo USB

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

Domínios associados (Universal Links)

ios: {
  associatedDomains: [
    "applinks:shop.example.com",
    "webcredentials:shop.example.com", // Autopreenchimento de Senha (opcional)
  ],
},

• Hospede apple-app-site-association no domínio - veja iOS Universal Links.
• O prefixo deve ser applinks: - não nomes de host brutos.
• Reconstrua após alterações - OTA não pode adicionar domínios associados.

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

Keychain e app groups

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", // quando a extensão precisa ler o mesmo segredo
});

• Os identificadores de app group devem corresponder entre o app principal e as extensões (widgets).
• O compartilhamento do Keychain requer um grupo de acesso idêntico em ambos os entitlements dos targets.

Modos de background

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

O que isto demonstra:

• Entitlements fluem da configuração → .entitlements no prebuild.
• Push requer portal + reconstrução binária + teste em dispositivo.
• Domínios associados pareiam com arquivos AASA hospedados.
• Modos de background devem refletir caminhos de código reais - não copiar e colar do Stack Overflow.

Mergulho Profundo

O que são entitlements

Entitlements são pares chave-valor em YourApp.entitlements que a Apple assina digitalmente no IPA. Eles controlam o acesso a APIs:

<!-- Trecho gerado - não edite manualmente sob CNG -->
<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:shop.example.com</string>
</array>
<key>aps-environment</key>
<string>development</string> <!-- production em builds da App Store -->

Push de desenvolvimento vs. produção

O EAS define isso a partir do perfil de distribuição. Sintomas de incompatibilidade: o token registra, mas as notificações nunca chegam.

Config Plugins vs ios.entitlements

// Prefira campos de configuração de alto nível quando o Expo os documentar
ios: { associatedDomains: ["applinks:example.com"] }
 
// Use ios.entitlements para chaves sem campos de primeira classe
ios: {
  entitlements: {
    "com.apple.developer.networking.networkextension": ["app-proxy-provider"],
  },
}
 
// Ou um plugin de configuração local com withEntitlementsPlist

Veja Config Plugins - withEntitlementsPlist é a saída de emergência.

Verificando entitlements em um IPA construído

# Após eas build --local ou Arquivo Xcode
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

Compare a saída com app.config.ts antes de culpar o código da aplicação.

Armadilhas

• Editar Signing & Capabilities no Xcode sob CNG - sobrescrito no prebuild. Correção: apenas app.config.ts.
• Prefixo applinks: ausente - domínio associado ignorado silenciosamente. Correção: applinks:host.example.com.
• Esperar que OTA adicione push ou domínios - entitlements são nativos. Correção: novo eas build.
• UIBackgroundModes sem implementação - rejeição da Diretriz 2.5.4. Correção: remover modos não utilizados.
• Expo Go para QA de link universal - bundle ID incorreto. Correção: dev client com seu bundleIdentifier.
• Widget lê keychain mas sem app group - a extensão não consegue ver os dados do app principal. Correção: identificadores group. correspondentes - veja App Extensions & Widgets.

Alternativas

FAQs

Relacionados

• iOS Universal Links - Hospedagem e verificação AASA
• Push Notification Deep Links - toque → roteamento
• App Extensions & Widgets - app groups e entitlements de extensão
• Config Plugins - withEntitlementsPlist
• iOS Credentials & Provisioning - chaves APNs e perfis
• Background Sync & TaskManager - modo de background processing

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0, e Expo SDK 57 (expo ~57.0.4).