添加 iOS App Clip 目标
本指南介绍了如何手动向现有 Flutter 项目或 add-to-app 项目添加另一个渲染 Flutter 的 iOS App Clip 目标。
要查看可工作的示例,请参阅 GitHub 上的 App Clip 示例。
步骤 1 - 打开项目
#打开您的 iOS Xcode 项目,例如完整 Flutter 应用的 ios/Runner.xcworkspace
。
步骤 2 - 添加 App Clip 目标
#2.1
在项目导航器中点击您的项目以显示项目设置。
在目标列表底部按 **+** 以添加新目标。

2.2
为您的新目标选择 **App Clip** 类型。

2.3
在对话框中输入新目标的详细信息。
为“界面 (Interface)”选择 **Storyboard**。
为“语言 (Language)”选择与原始目标相同的语言。
(换句话说,为了简化设置,请勿为 Objective-C 主目标创建 Swift App Clip 目标,反之亦然。)

2.4
在接下来的对话框中,为新目标激活新方案。

2.5
回到项目设置,打开 **Build Phases** 标签页。将 **Embedded App Clips** 拖动到 **Thin Binary** 上方。

步骤 3 - 移除不必要的文件
#3.1
在项目导航器中,在新创建的 App Clip 组中,删除除 Info.plist
和 <app clip target>.entitlements
之外的所有内容。

将文件移至废纸篓。
3.2
如果您不使用 SceneDelegate.swift
文件,请在 Info.plist
中移除对它的引用。
打开 App Clip 组中的 Info.plist
文件。删除 **Application Scene Manifest** 的整个字典条目。

步骤 4 - 共享构建配置
#此步骤对于 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)
步骤 5 - 共享代码和资产
#选项 1 - 共享所有内容
#如果目的是在标准应用和 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
复选框组中。

选项 2 - 为 App Clip 自定义 Flutter 启动
#在这种情况下,不要删除 步骤 3 中列出的所有内容。相反,请使用脚手架和 iOS add-to-app API 来执行 Flutter 的自定义启动。例如,显示一个 自定义 Flutter 路由。
步骤 6 - 添加 App Clip 关联域
#这是 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
回到项目设置,选择主应用的 target,打开 **Build Settings** 标签页。将 **Code Signing Entitlements** 设置为主应用创建的第二个权限文件的相对路径。

步骤 7 - 集成 Flutter
#这些步骤对于 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**。
换句话说,与主应用目标的构建阶段相同。

这确保了在运行 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 bundle 中。
步骤 8 - 集成插件
#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, '12.0'
并将版本设置为两个目标中 iOS Deployment Target 的最低版本。
对于 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
运行
#现在,您可以通过从方案下拉菜单中选择您的 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>