Adicionar um App Clip a um App Expo

Quando Usar

Use esta funcionalidade quando precisar adicionar um destino de App Clip para iOS a um app Expo. Use quando o usuário mencionar App Clip, AASA, apple-app-site-association, appclips, smart app banner, ou quiser enviar um Clip leve para iOS invocado a partir de uma URL junto com o app principal.

Adiciona um destino de App Clip para iOS a um projeto Expo. O Clip fica em targets/clip/, é enviado junto com o app principal e é invocado a partir de uma URL no domínio do app através de um arquivo Apple App Site Association (AASA).

O ID do pacote do app principal se torna com.<username>.<app-name> e o do Clip é derivado automaticamente como <parent>.clip (por exemplo, com.bacon.may20.clip).

1. Definir bundleIdentifier e appleTeamId

bun create target avisa se estes estiverem faltando. Adicione a app.json:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.<username>.<app-name>",
      "appleTeamId": "XX57RJ5UTD"
    }
  }
}

2. Adicionar o destino do App Clip

bun create target clip

Isso instala @bacons/apple-targets, o adiciona ao array plugins em app.json e escreve:

• targets/clip/expo-target.config.js — o plugin de configuração do destino
• targets/clip/Info.plist — Info.plist do Clip
• targets/clip/AppDelegate.swift, Assets.xcassets, etc.

Escolha um bom ícone ou reutilize o existente definido no app — verifique-o com bunx expo config sob a chave icon ou ios.icon.

3. Configurar domínios associados

O app principal e o Clip precisam da permissão Associated Domains apontando para o domínio que hospeda o arquivo AASA.

Em app.json, adicione ambas as entradas applinks: (principal) e appclips: (invocação do Clip):

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "applinks:may20.expo.app",
        "appclips:may20.expo.app"
      ]
    }
  }
}

Em targets/clip/expo-target.config.js, declare a permissão do Clip:

/** @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} */
module.exports = (config) => ({
  type: "clip",
  icon: "https://github.com/expo.png",
  entitlements: {
    "com.apple.developer.associated-domains": ["appclips:may20.expo.app"],
  },
});

Se você pular isso, expo prebuild imprimirá: Apple App Clip may require the associated domains entitlement but none were found.

4. Registrar IDs de pacote e criar a entrada na App Store

bunx setup-safari

Isso faz login na conta do Apple Developer, registra com.bacon.may20, cria a entrada no App Store Connect e imprime:

• Um starter apple-app-site-association JSON
• Uma tag <meta name="apple-itunes-app"> com o ID do app no iTunes
• Team ID, iTunes ID e Bundle ID

5. Hospedar o arquivo AASA

Os App Clips são invocados quando o iOS busca https://<your-domain>/.well-known/apple-app-site-association e encontra uma entrada appclips correspondente.

mkdir -p public/.well-known
touch public/.well-known/apple-app-site-association

Cole o JSON que setup-safari imprimiu, mas adicione um bloco appclips para o ID completo do app do Clip (<TeamID>.<ClipBundleID>). A saída de setup-safari cobre apenas o app principal:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["XX57RJ5UTD.com.bacon.may20"],
        "components": [{ "/": "*", "comment": "Matches all routes" }]
      }
    ]
  },
  "appclips": {
    "apps": ["XX57RJ5UTD.com.bacon.may20.clip"]
  },
  "activitycontinuation": {
    "apps": ["XX57RJ5UTD.com.bacon.may20"]
  },
  "webcredentials": {
    "apps": ["XX57RJ5UTD.com.bacon.may20"]
  }
}

Observações:

• O arquivo não tem extensão e nenhum requisito de Content-Type além de ser servido como está. A exportação estática do Expo Router serve arquivos em public/ literalmente.
• O bloco appclips é o que permite que uma URL no domínio inicie o Clip.
• webcredentials é usado para compartilhar credenciais entre o site, o app principal e o App Clip.
• activitycontinuation é opcional e usado para compartilhar o link entre mobile e desktop. Deve ser usado com Head do expo-router — veja https://docs.expo.dev/router/advanced/apple-handoff/
• Detalhes de notação e desativação de rotas: https://sosumi.ai/documentation/xcode/supporting-associated-domains

6. Adicionar a meta tag Smart App Banner

Crie src/app/+html.tsx (o shell HTML do Expo Router) e adicione a tag de setup-safari. Crie o template versionado se ele não existir:

bunx expo customize src/app/+html.tsx

Adicione a meta tag ao <head>:

…