Universal Links do iOS

Domínios associados, apple-app-site-association e hospedagem em CDN - o guia do iOS para abrir URLs de marketing https:// diretamente no seu app Expo SDK 57 sem uma folha de desambiguação de esquema personalizado.

Receita

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

// 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/*"]
      }
    ]
  }
}

Quando usar isso:

• Campanhas de e-mail e SMS usam links https:// que devem abrir o app quando instalado.
• Você deseja uma transição perfeita do seu site de marketing sem prompts myapp://.
• Listagens na App Store e smart banners referenciam as mesmas URLs canônicas do app.
• Você precisa que o iOS verifique a propriedade do domínio antes de abrir links no app.

Exemplo de Trabalho

Configuração de ponta a ponta para https://shop.example.com/orders/* em um app Expo com prebuild.

Passo 1 - Entitlements via 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;

Passo 2 - Hospede AASA no seu CDN

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

Sirva em ambos os caminhos (a Apple verifica qualquer um):

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

Passo 3 - Cabeçalhos de resposta do CDN

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

• Sem redirecionamentos 301/302 na URL AASA - a Apple rejeita arquivos de associação redirecionados.
• O arquivo deve ser não assinado - nenhuma extensão .json é necessária; corpo JSON bruto.
• Substitua ABCDE12345 pelo seu Apple Team ID do portal do Desenvolvedor.

Passo 4 - Tela do 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>
  );
}

Passo 5 - Construa e verifique

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

O que isso demonstra:

• Entitlement associatedDomains gerado no prebuild.
• Regras de caminho AASA limitando quais URLs abrem o app.
• Cabeçalhos CDN necessários para o crawler da Apple.
• Correspondência de rota dinâmica do Expo Router /orders/42.
• Teste no simulador antes do TestFlight.

Mergulho Profundo

Como Funciona

• Na instalação, o iOS busca o AASA de cada domínio applinks: nos seus entitlements.
• A Apple armazena em cache os dados de associação no dispositivo - as atualizações se propagam lentamente (horas, às vezes dias).
• Quando o usuário toca em um link correspondente https://, o iOS abre seu app e passa a URL para o React Native.
• Se a verificação falhar ou o caminho for excluído, o Safari lida com a URL normalmente.
• Esquemas personalizados ainda funcionam em paralelo - universal links são preferidos para marketing.

Regras de Caminho AASA

Checklist de CDN

Notas do iOS

# Valide o AASA com o CDN da Apple (o dispositivo eventualmente verá os mesmos dados)
curl -s "https://app-site-association.cdn-apple.com/a/v1/shop.example.com" | jq .

• Após alterar o AASA, atualize o cache do CDN ou purgue os nós de borda - arquivos desatualizados causam "funciona em staging, quebrado em produção".
• Builds do TestFlight usam o ID de bundle de produção - corresponda exatamente ao appID.
• Usuários que escolheram "Abrir no Safari" desativam universal links por site até serem redefinidos nas Configurações.

Armadilhas

• Team ID incorreto em appID - o link abre o Safari silenciosamente. Correção: TEAMID.bundleIdentifier do Apple Developer → Membership.
• AASA atrás de redirecionamento - redirecionamento de www para apex quebra a busca. Correção: sirva o AASA no host exato em associatedDomains.
• Esquecer de reconstruir após adicionar associatedDomains - entitlement ausente no IPA. Correção: eas build --platform ios após alteração de configuração.
• Incluir /api/* em paths - respostas JSON da API não devem abrir o app. Correção: regras NOT explícitas ou prefixos estreitos.
• Esperar atualizações instantâneas do AASA - o iOS armazena em cache agressivamente. Correção: altere caminhos apenas com campanhas de marketing versionadas; mantenha caminhos antigos durante a transição.
• Universal link do mesmo domínio em WKWebView - o navegador in-app pode não fazer a transição. Correção: use SFSafariViewController ou <a target="_blank"> para abrir externamente.

Alternativas

FAQs

Relacionados

• Noções Básicas de Deep Linking - visão geral de esquema vs HTTPS
• API expo-linking - padrões de análise e listener
• Android App Links - verificação paralela do Android
• Matriz de Teste de Deep Link - matriz de simulador e dispositivo iOS
• ../expo-router/expo-router-basics/expo-router-basics.md - layout de arquivos de rota
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - regras de revisão de deep-link

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).