新增 iOS App Clip 目標

本指南介紹瞭如何手動將另一個支援 Flutter 渲染的 iOS App Clip 目標新增到現有的 Flutter 專案或 add-to-app 專案中。

若要檢視可執行的示例，請參閱 GitHub 上的 App Clip 示例。

開啟你的 iOS Xcode 專案，例如完整 Flutter 應用的 ios/Runner.xcworkspace。

2.1

在專案導航器中點選你的專案以顯示專案設定。

點選目標列表底部的 + 號以新增新目標。

2.2

為你的新目標選擇 App Clip 型別。

2.3

在對話方塊中輸入新目標的詳細資訊。

介面（Interface）選擇 Storyboard。

語言（Language）選擇與原始目標相同的語言。

（換句話說，為了簡化設定，請勿在 Objective-C 主目標中建立 Swift App Clip 目標，反之亦然。）

2.4

在接下來的對話方塊中，為新目標啟用新方案（Scheme）。

2.5

回到專案設定，開啟 Build Phases 選項卡。將 Embedded App Clips 拖動到 Thin Binary 上方。

3.1

在專案導航器中，在新建立的 App Clip 分組中，刪除除 Info.plist 和 <app clip target>.entitlements 之外的所有內容。

將檔案移至廢紙簍。

3.2

如果你不使用 SceneDelegate.swift 檔案，請移除 Info.plist 中對它的引用。

開啟 App Clip 分組中的 Info.plist 檔案。刪除 Application Scene Manifest 的整個字典條目。

此步驟對於 add-to-app 專案不是必需的，因為 add-to-app 專案有其自定義的構建配置和版本。

4.1

回到專案設定，選擇專案條目，而不是任何特定目標。

在 Info 選項卡下的 Configurations 可展開組中，展開 Debug、Profile 和 Release 條目。

對於每一項，在 App Clip 目標的下拉選單中選擇與普通應用目標所選條目相同的值。

這使你的 App Clip 目標能夠訪問 Flutter 所需的構建設定。

將 iOS Deployment Target 設定為至少 16.0，以利用 15MB 的大小限制。

4.2

在 App Clip 分組的 Info.plist 檔案中，設定

• Build version string (short) 為 $(FLUTTER_BUILD_NAME)
• Bundle version 為 $(FLUTTER_BUILD_NUMBER)

假設目標是在標準應用和 App Clip 中顯示相同的 Flutter UI，則共享相同的程式碼和資源。

對於以下每個檔案：Main.storyboard、Assets.xcassets、LaunchScreen.storyboard、GeneratedPluginRegistrant.m 和 AppDelegate.swift（如果使用 Objective-C，還包括 Supporting Files/main.m），選擇該檔案，然後在檢查器（Inspector）的第一項選項卡中，將 App Clip 目標勾選加入 Target Membership 複選框組。

在這種情況下，不要刪除 第 3 步 中列出的所有內容。相反，使用腳手架和 iOS add-to-app API 來執行 Flutter 的自定義啟動。例如，顯示一個 自定義 Flutter 路由。

這是 App Clip 開發的標準步驟。請參閱 Apple 官方文件。

6.1

開啟 <app clip target>.entitlements 檔案。新增一個 Associated Domains 陣列型別。向陣列中新增一行內容為 appclips:<your bundle id>。

6.2

同樣的關聯域名許可權也需要新增到你的主應用中。

將 <app clip target>.entitlements 檔案從 App Clip 分組複製到主應用分組，並將其重新命名為與主目標相同的名稱，例如 Runner.entitlements。

開啟該檔案並刪除主應用許可權檔案中的 Parent Application Identifiers 條目（App Clip 的許可權檔案需保留該條目）。

6.3

回到專案設定，選擇主應用的 目標，開啟 Build Settings 選項卡。將 Code Signing Entitlements 設定為為主應用建立的第二個許可權檔案的相對路徑。

這些步驟對於 add-to-app 來說不是必需的。

7.1

對於 Swift 目標，將 Objective-C Bridging Header 構建設定設為 Runner/Runner-Bridging-Header.h

換句話說，與主應用目標的構建設定保持一致。

7.2

現在開啟 Build Phases 選項卡。按下 + 號並選擇 New Run Script Phase。

將該新階段拖動到 Dependencies 階段下方。

展開該新階段並在指令碼內容中新增此行

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build

取消勾選 Based on dependency analysis。

換句話說，與主應用目標的構建階段保持一致。

這確保了你的 Flutter Dart 程式碼在執行 App Clip 目標時會被編譯。

7.3

再次按下 + 號並選擇 New Run Script Phase。將其保留為最後一個階段。

這次，新增

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" embed_and_thin

取消勾選 Based on dependency analysis。

換句話說，與主應用目標的構建階段保持一致。

這確保了你的 Flutter 應用和引擎被嵌入到 App Clip 包中。

8.1

開啟你的 Flutter 專案或 add-to-app 宿主專案的 Podfile。

對於完整 Flutter 應用，替換以下部分

target 'Runner' do
  use_frameworks!
  use_modular_headers!
​
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

為

use_frameworks!
use_modular_headers!
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
​
target 'Runner'
target '<name of your App Clip target>'

在檔案頂部，同時取消 platform :ios, '13.0' 的註釋，並將版本設定為兩個目標中較低的 iOS 部署目標版本。

對於 add-to-app，新增到

target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end

為

target 'MyApp' do
  install_all_flutter_pods(flutter_application_path)
end
​
target '<name of your App Clip target>'
  install_all_flutter_pods(flutter_application_path)
end

8.2

從命令列進入你的 Flutter 專案目錄，然後安裝 Pod

cd ios
pod install

現在，你可以透過從方案（Scheme）下拉選單中選擇你的 App Clip 目標、選擇 iOS 16 或更高版本的裝置，然後按下執行按鈕，來從 Xcode 執行你的 App Clip 目標。

若要測試從零開始啟動 App Clip，請參閱 Apple 關於 測試 App Clip 啟動體驗 的文件。

遺憾的是，由於網路許可權限制，flutter attach 無法自動發現 App Clip 中的 Flutter 會話。

你必須將其複製並貼上回 flutter attach 命令中以進行連線。

例如

flutter attach --debug-uri <copied URI>