add-app-clip

Expo アプリに App Clip を追加する

Expo プロジェクトに iOS App Clip ターゲットを追加します。Clip は targets/clip/ に配置され、親アプリと一緒に配信されます。また、Apple App Site Association（AASA）ファイルを介して、アプリのドメイン上の URL から起動されます。

親アプリのバンドル ID は com.<username>.<app-name> になり、Clip のバンドル ID は <parent>.clip として自動的に導出されます（例：com.bacon.may20.clip）。

1. bundleIdentifier と appleTeamId を設定する

これらが設定されていない場合、bun create target は警告を表示します。app.json に追加します：

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

2. App Clip ターゲットを追加する

bun create target clip

これにより、@bacons/apple-targets がインストールされ、app.json の plugins 配列に追加され、以下のファイルが書き込まれます：

• targets/clip/expo-target.config.js — ターゲットの設定プラグイン
• targets/clip/Info.plist — Clip の Info.plist
• targets/clip/AppDelegate.swift、Assets.xcassets など

適切なアイコンを選ぶか、アプリで定義済みのアイコンを再利用してください。bunx expo config を実行し、icon または ios.icon キーを確認します。

3. 関連付けドメインを設定する

親アプリと Clip のそれぞれで、AASA ファイルをホストするドメインを指定する Associated Domains エンタイトルメントが必要です。

app.json に applinks:（親アプリ）と appclips:（Clip の起動）の両方のエントリーを追加します：

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

targets/clip/expo-target.config.js で、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"],
  },
});

これを省略すると、expo prebuild に Apple App Clip may require the associated domains entitlement but none were found と表示されます。

4. バンドル ID を登録し、App Store のエントリーを作成する

bunx setup-safari

これにより Apple Developer アカウントにログインし、com.bacon.may20 を登録して、App Store Connect のエントリーを作成します。次の内容が出力されます：

• 初期設定用の apple-app-site-association JSON
• iTunes アプリ ID を含む <meta name="apple-itunes-app"> タグ
• Team ID、iTunes ID、Bundle ID

5. AASA ファイルをホストする

iOS が https://<your-domain>/.well-known/apple-app-site-association を取得し、一致する appclips エントリーを見つけると、App Clip が起動されます。

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

setup-safari が出力した JSON を貼り付けます。ただし、Clip の完全なアプリ ID（<TeamID>.<ClipBundleID>）を指定する appclips ブロックを追加してください。setup-safari の出力には親アプリのみが含まれます：

{
  "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"]
  }
}

注意事項：

• ファイルに拡張子は不要で、Content-Type に関する要件もありません。ファイルはそのまま配信してください。Expo Router の静的エクスポートでは、public/ 内のファイルがそのまま配信されます。
• appclips ブロックにより、ドメイン上の URL から Clip を起動できるようになります。
• webcredentials は、ウェブサイト、親アプリ、App Clip 間で認証情報を共有するために使用されます。
• activitycontinuation は任意で、モバイルとデスクトップ間でリンクを共有するために使用されます。expo-router の Head と併用する必要があります。https://docs.expo.dev/router/advanced/apple-handoff/ を参照してください。
• 記法とルートの無効化に関する詳細：https://sosumi.ai/documentation/xcode/supporting-associated-domains

6. Smart App Banner のメタタグを追加する

src/app/+html.tsx（Expo Router の HTML シェル）を作成し、setup-safari のタグを追加します。バージョン付きのテンプレートが存在しない場合は作成します：

bunx expo customize src/app/+html.tsx

<head> にメタタグを追加します：

import { ScrollViewStyleReset } from "expo-router/html";

export default function Root({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta name="apple-itunes-app" content="app-id=6771566491" />
        <ScrollViewStyleReset />
      </head>
      <body>{children}</body>
    </html>
  );
}

ウェブサイトにインストールカードではなく App Clip カードを表示するには、次のようにします：

<meta
  name="apple-itunes-app"
  content="app-id=6771566491, app-clip-bundle-id=com.bacon.may20.clip, app-clip-display=card"
/>

7. ウェブサイトをデプロイする

iOS が関連付けを信頼するには、AASA ファイルを公開しておく必要があります。EAS Hosting を使用します：

bunx expo export -p web
eas deploy --prod

これにより、/.well-known/apple-app-site-association を含むサイトが https://<slug>.expo.app に公開されます。次のように確認します：

curl https://may20.expo.app/.well-known/apple-app-site-association

8. 権限を反映する

prebuild の後、親アプリの権限を確認します：

npx expo config --type introspect

infoPlist オブジェクトを確認し、Clip から対応する API を使用できるように、権限キーを App Clip の Info.plist に反映します。

Clip のターゲット設定で deploymentTarget: "17.6" を設定します。iOS 17.6 では App Clip の最小サイズ制限が引き上げられています。

アプリでプッシュ通知または位置情報サービスを使用する場合は、必要な権限をリクエストするために App Clip の Info.plist に追加します：

<key>NSAppClip</key>
<dict>
  <key>NSAppClipRequestEphemeralUserNotification</key>
  <false/>
  <key>NSAppClipRequestLocationConfirmation</key>
  <true/>
</dict>

9. ビルドして TestFlight に提出する

bunx testflight

以下が実行されます。

1. eas.json が存在しない場合は生成します。
2. 両方のターゲット（親アプリと Clip）の認証情報を設定します。それぞれに個別のプロビジョニングプロファイルが必要ですが、1 つの Distribution Certificate を共有できます。
3. ケイパビリティを同期します。Clip ターゲットで Enabled: Associated Domains が有効になっていることを確認してください。
4. ビルドしてアップロードし、TestFlight への提出をスケジュールします。

10. App Clip のメタデータを設定する

既存の App Store メタデータをローカルに取得します。

eas metadata:pull

store.config.json に apple.appClip を追加します。最大 3 つの起動 URL を設定でき、Web ページから Clip を起動できます。

{
  "configVersion": 0,
  "apple": {
    "appClip": {
      "defaultExperience": {
        "action": "PLAY",
        "releaseWithAppStoreVersion": true,
        "reviewDetail": {
          "invocationUrls": ["https://may20.expo.app/", null, null]
        },
        "info": {
          "en-US": {
            "subtitle": "Instantly native with Expo",
            "headerImage": "store/apple/app-clip/en-US/asc-app-clip.png"
          }
        }
      }
    }
  }
}

headerImage は不透明度のない 1800x1200 の PNG である必要があります。

ストアに反映します。

eas metadata:push

Apple が推奨する App Clip メタデータのガイドライン：https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip

得られるもの

• 親アプリのターゲット：com.bacon.may20
• App Clip のターゲット：com.bacon.may20.clip。targets/clip/ に配置されます
• https://may20.expo.app/.well-known/apple-app-site-association でホストされる AASA
• すべての Web ルートに Smart App Banner のメタタグを設定
• すべてのルートをネイティブ版の対応箇所にリンク
• Clip を組み込んだ親アプリの TestFlight ビルド

Apple がドメイン上の URL から Clip を起動すると、iOS は targets/clip/ のエントリーポイントを開き、React Native アプリを読み込みます。

ネイティブ検出（任意）

JS から App Clip 内で実行中かどうかを検出し、フルアプリのインストールを促すには、navigator.appClip.prompt() を公開するローカル Expo モジュール（bunx create-expo-module --local）を作成します。

Swift モジュール、TypeScript インターフェース、使用方法については、./references/native-module.md を参照してください。

参考資料

• ./references/native-module.md — App Clip のコンテキストを検出し、SKOverlay のインストールプロンプトを表示するローカル Expo モジュール