新增 iOS App Clip 目標

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

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

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

2.1

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

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

2.2

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

2.3

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

選擇 **Storyboard** 作為介面。

為 **Language** 選擇與您的原始目標相同的語言。

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

2.4

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

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**（iOS 部署目標）設定為至少 **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），選擇檔案，然後在檢查器的第一個選項卡中，在 Target Membership（目標成員資格）複選框組中也包含 App Clip 目標。

在這種情況下，請勿刪除 步驟 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（Objective-C 橋接標頭檔案）構建設定設定為 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**（基於依賴分析）。

換句話說，與主應用目標的構建階段相同。

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

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

現在，您可以透過 Xcode 執行您的 App Clip 目標，方法是：從方案下拉選單中選擇您的 App Clip 目標，選擇 iOS 16 或更高版本的裝置，然後按執行。

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

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

然後，您必須將其複製並貼上回 flutter attach 命令以進行連線。

例如

flutter attach --debug-uri <copied URI>