添加 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>