スキルOfficialdevelopment

📱add-app-clip

プラグイン: expo
ソース: GitHub で見る ↗

説明

iOSのApp ClipターゲットをExpoアプリに追加します。次のような場合に使用: ユーザーがApp Clip、AASA、apple-app-site-association、appclips、スマートアプリバナーについて言及した場合、またはURLから起動する軽量なiOS Clipを親アプリと併せてリリースしたい場合。

原文を表示

Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.

ユースケース

✓App ClipターゲットをExpoアプリに追加する
✓URLから起動する軽量なiOS Clipをリリースする
✓AASAやapple-app-site-associationを設定する

本文（日本語訳）

Expo AppにApp Clipを追加する

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

親アプリのBundle IDは com.<username>.<app-name> となり、ClipのBundle 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 — ターゲットのconfig plugin
targets/clip/Info.plist — ClipのInfo.plist
targets/clip/AppDelegate.swift、Assets.xcassets など

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

3. Associated Domainsを設定する

親アプリと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のエンタイトルメントとしてAssociated Domainsを宣言します:

/** @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. Bundle IDを登録し、App Storeエントリを作成する

bunx setup-safari

このコマンドはApple Developerアカウントにログインし、com.bacon.may20 を登録して App Store Connectのエントリを作成したうえで、以下の情報を出力します:

apple-app-site-association JSONのひな形
iTunes app 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"]
  }
}

補足:

このファイルは拡張子なしで配置します。Expo Routerの静的エクスポートでは public/ 内のファイルがそのまま配信されるため、Content-Type の指定は不要です。
appclips ブロックがあることで、そのドメイン上のURLからClipを起動できます。
webcredentials は、Webサイト・親アプリ・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のmetaタグを追加する

Expo RouterのHTMLシェルである src/app/+html.tsx を作成し、 setup-safari が出力したタグを追加します。ファイルが存在しない場合は、バージョン対応済みのテンプレートを生成してください:

bunx expo customize src/app/+html.tsx

<head> にmetaタグを追加します:

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>
  );
}

WebサイトにアプリインストールカードではなくApp Clipカードを表示させる場合は、以下を使用します:

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

7. Webサイトをデプロイする

AASAファイルが公開されていなければ、iOSはそのassociationを信頼しません。 EAS Hosting を使用してデプロイします:

bunx expo export -p web
eas deploy --prod

これにより https://<slug>.expo.app にサイト（/.well-known/apple-app-site-association を含む）が公開されます。以下のコマンドで確認できます:

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のターゲットconfigにはiOS 17.6以降を対象とするよう 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

このコマンドは以下を実行します:

eas.json が存在しない場合は生成する。
両方のターゲット（親アプリ + Clip）のクレデンシャルをセットアップする。各ターゲットは独自のProvisioning Profileを持ちますが、単一のDistribution Certificateを共有できます。
ケイパビリティを同期する — Clipターゲットの Enabled: Associated Domains に注意してください。
ビルド・アップロード・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 は透過なしの1800×1200 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/ に配置）
AASAのホスト先: https://may20.expo.app/.well-known/apple-app-site-association
すべてのWebルートにSmart App Bannerのmetaタグを設置
すべてのルートが対応するネイティブ画面にリンク済み
Clipを内包した親アプリのTestFlightビルド

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

ネイティブ検出（オプション）

JSがApp Clip内で動作していることを検知し、フルアプリのインストールプロンプトを表示させるには、ローカルExpo module（bunx create-expo-module --local）を作成して navigator.appClip.prompt() を公開します。

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

参考資料

./references/native-module.md — App Clipコンテキストの検出とSKOverlayインストールプロンプトの表示に使用するローカルExpo module

原文（English）を表示

Add an App Clip to an Expo App

Adds an iOS App Clip target to an Expo project. The Clip lives in targets/clip/, ships alongside the parent app, and is invoked from a URL on the app's domain via an Apple App Site Association (AASA) file.

The parent app's bundle ID becomes com.<username>.<app-name> and the Clip's is automatically derived as <parent>.clip (e.g. com.bacon.may20.clip).

1. Set `bundleIdentifier` and `appleTeamId`

bun create target warns if these are missing. Add to app.json:

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

2. Add the App Clip target

bun create target clip

This installs @bacons/apple-targets, adds it to the plugins array in app.json, and writes:

targets/clip/expo-target.config.js — the target's config plugin
targets/clip/Info.plist — Clip Info.plist
targets/clip/AppDelegate.swift, Assets.xcassets, etc.

Pick a good icon or reuse the existing one defined in the app — check it with bunx expo config under the icon or ios.icon key.

3. Wire up associated domains

The parent app and the Clip each need the Associated Domains entitlement pointing at the domain that hosts the AASA file.

In app.json, add both applinks: (parent) and appclips: (Clip invocation) entries:

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

In targets/clip/expo-target.config.js, declare the Clip's entitlement:

/** @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"],
  },
});

If you skip this, expo prebuild will print: Apple App Clip may require the associated domains entitlement but none were found.

4. Register bundle IDs and create the App Store entry

bunx setup-safari

This logs in to the Apple Developer account, registers com.bacon.may20, creates the App Store Connect entry, and prints:

A starter apple-app-site-association JSON
A <meta name="apple-itunes-app"> tag with the iTunes app id
Team ID, iTunes ID, and Bundle ID

5. Host the AASA file

App Clips are invoked when iOS fetches https://<your-domain>/.well-known/apple-app-site-association and finds a matching appclips entry.

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

Paste the JSON setup-safari printed, but add an appclips block for the Clip's full app ID (<TeamID>.<ClipBundleID>). The output of setup-safari only covers the parent app:

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

Notes:

The file has no extension and no Content-Type requirements beyond being served as-is. Expo Router static export serves files in public/ verbatim.
The appclips block is what lets a URL on the domain launch the Clip.
webcredentials is used for sharing credentials between the website, parent app, and the App Clip.
activitycontinuation is optional and used for sharing the link between mobile and desktop. Must be used with Head from expo-router — see https://docs.expo.dev/router/advanced/apple-handoff/
Notation and route-disabling details: https://sosumi.ai/documentation/xcode/supporting-associated-domains

6. Add the Smart App Banner meta tag

Create src/app/+html.tsx (Expo Router's HTML shell) and add the tag from setup-safari. Create the versioned template if it doesn't exist:

bunx expo customize src/app/+html.tsx

Add the meta tag to the <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>
  );
}

To make the website show the App Clip card instead of the install card, use:

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

7. Deploy the website

The AASA file must be live before iOS will trust the association. Use EAS Hosting:

bunx expo export -p web
eas deploy --prod

This publishes the site (including /.well-known/apple-app-site-association) at https://<slug>.expo.app. Verify:

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

8. Mirror permissions

Inspect the parent app's permissions after prebuild:

npx expo config --type introspect

Look at the infoPlist object — mirror the permission keys in the App Clip's Info.plist so matching APIs can be used from the Clip.

Set deploymentTarget: "17.6" in the Clip's target config — App Clips have a higher minimum size limit in iOS 17.6.

If the app uses push notifications or location services, add to the App Clip's Info.plist to request the necessary permissions:

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

9. Build and submit to TestFlight

bunx testflight

This will:

Generate an eas.json if missing.
Set up credentials for both targets (parent + Clip). Each gets its own provisioning profile but can share a single Distribution Certificate.
Sync capabilities — note Enabled: Associated Domains for the Clip target.
Build, upload, and schedule a TestFlight submission.

10. Configure App Clip metadata

Pull existing App Store metadata to local:

eas metadata:pull

Add apple.appClip to store.config.json. Up to 3 invocation URLs can launch the Clip from a web page:

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

The headerImage must be a 1800x1200 PNG with no opacity.

Push back to the store:

eas metadata:push

Apple's recommended App Clip metadata guidelines: https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip

What you get

Parent app target: com.bacon.may20
App Clip target: com.bacon.may20.clip, lives in targets/clip/
AASA hosted at https://may20.expo.app/.well-known/apple-app-site-association
Smart App Banner meta tag on every web route
Every route linked to its native counterpart
TestFlight build of the parent app with the Clip embedded

Once Apple invokes the Clip from a URL on the domain, iOS opens targets/clip/'s entry point which loads the React Native app.

Native detection (optional)

To let JS detect when it's running inside an App Clip and present an install prompt for the full app, create a local Expo module (bunx create-expo-module --local) that exposes navigator.appClip.prompt().

See ./references/native-module.md for the Swift module, TypeScript interface, and usage.

References

./references/native-module.md — Local Expo module to detect App Clip context and present the SKOverlay install prompt

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。