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

在对话框中输入您的新目标详细信息。

为界面选择 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 设置为至少 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:<您的 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 设置设置为为主要应用创建的第二个权利文件的相对路径。

这些步骤对于 add-to-app 来说不是必需的。

7.1

对于 Swift target，将 Objective-C Bridging Header 构建设置设置为 Runner/Runner-Bridging-Header.h

换句话说，与主应用 target 的构建设置相同。

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。

换句话说，与主应用 target 的构建阶段相同。

这可确保在运行 App Clip target 时编译您的 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。

换句话说，与主应用 target 的构建阶段相同。

这可确保您的 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 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

现在，您可以从 Xcode 通过从方案下拉菜单中选择您的 App Clip 目标，选择 iOS 16 或更高版本的设备并按运行来运行您的 App Clip 目标。

要测试从头开始启动 App Clip，请参阅 Apple 的关于 测试您的 App Clip 的启动体验 的文档。

不幸的是，由于网络权限限制，flutter attach 无法自动发现 App Clip 中的 Flutter 会话。

您必须将其复制并粘贴回 flutter attach 命令才能连接。

例如

flutter attach --debug-uri <copied URI>