description bug_report

添加 iOS App Clip 目标

内容

步骤 1 - 打开项目
步骤 2 - 添加 App Clip 目标
步骤 3 - 删除不需要的文件
步骤 4 - 共享构建配置
步骤 5 - 共享代码和资产
- 选项 1 - 共享所有内容
- 选项 2 - 为 App Clip 自定义 Flutter 启动
步骤 6 - 添加 App Clip 关联域
步骤 7 - 集成 Flutter
步骤 8 - 集成插件
运行
调试、热重载

本指南介绍如何将另一个 Flutter 渲染 iOS App Clip 目标手动添加到现有的 Flutter 项目或 add-to-app 项目。

要查看工作示例，请参阅 GitHub 上的 App Clip 示例。

步骤 1 - 打开项目

打开你的 iOS Xcode 项目，例如全 Flutter 应用的 ios/Runner.xcworkspace。

步骤 2 - 添加 App Clip 目标

2.1

在项目导航器中单击你的项目以显示项目设置。

按目标列表底部的 + 以添加新目标。

2.2

为你的新目标选择 App Clip 类型。

2.3

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

为界面选择 情节提要。

为语言选择与原始目标相同的语言。

（换句话说，为了简化设置，请勿为 Objective-C 主目标创建 Swift App Clip 目标，反之亦然。）

2.4

在以下对话框中，激活新目标的新方案。

2.5

回到项目设置中，打开构建阶段选项卡。将嵌入式 App Clip拖动到精简二进制文件上方。

步骤 3 - 删除不需要的文件

3.1

在项目导航器中，在新建的 App Clip 组中，删除除 Info.plist 和 <app clip target>.entitlements 之外的所有内容。

将文件移至废纸篓。

3.2

如果您不使用 SceneDelegate.swift 文件，请删除 Info.plist 中对它的引用。

在 App Clip 组中打开 Info.plist 文件。删除应用程序场景清单的整个词典条目。

对于添加至应用项目，此步骤不是必需的，因为添加至应用项目有其自定义的构建配置和版本。

4.1

回到项目设置中，现在选择项目条目，而不是任何目标。

在信息选项卡中，在配置可展开组下，展开调试、概要和发布条目。

对于每个条目，从 App Clip 目标的下拉菜单中选择与为普通应用目标选择的条目相同的值。

这使您的 App Clip 目标能够访问 Flutter 所需的构建设置。

将iOS 部署目标至少设置为16.0，以利用 15MB 大小限制。

4.2

在 App Clip 组的 Info.plist 文件中，设置

构建版本字符串（短）为 $(FLUTTER_BUILD_NAME)
捆绑包版本为 $(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 目标。

选项 2 - 为 App Clip 自定义 Flutter 启动

在这种情况下，不要删除步骤 3 中列出的所有内容。相反，使用脚手架和 iOS 添加到应用 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

回到项目设置，选择主应用的目标，打开构建设置选项卡。将代码签名权限设置设为主应用创建的第二个权限文件的相对路径。

步骤 7 - 集成 Flutter

这些步骤对于添加至应用来说不是必需的。

7.1

对于 Swift 目标，将 Objective-C 桥接头 构建设置设置为 Runner/Runner-Bridging-Header.h

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

7.2

现在打开构建阶段选项卡。按+ 号并选择新建运行脚本阶段。

将该新阶段拖动到依赖项阶段下方。

展开新阶段并将此行添加到脚本内容中

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

取消选中基于依赖项分析。

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

这可确保在运行 App Clip 目标时编译 Flutter Dart 代码。

7.3

按+ 号并再次选择新建运行脚本阶段。将其保留为最后一个阶段。

这次，添加

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

取消选中基于依赖项分析。

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

这可确保将 Flutter 应用和引擎嵌入到 App Clip 捆绑包中。

步骤 8 - 集成插件

8.1

为 Flutter 项目或添加至应用宿主项目打开 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 部署目标中较低的那个。

对于添加至应用，添加到

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 会话。

为了调试 App Clip 并使用热重载等功能，你必须在运行后从 Xcode 中的控制台输出中查找 Observatory URI。

然后你必须将其复制并粘贴回 flutter attach 命令以进行连接。

例如

flutter attach --debug-uri <copied URI>