构建和部署适用于 iOS 平台的 Safari 扩展

Jon Davis：大家好 我叫 Jon Davis 在 Safari 浏览器和 WebKit 团队 担任网页技术推广者 很高兴能带您了解如何构建和部署 适用于 iOS 平台的 Safari 扩展 iOS 平台目前有多种 不同类型的扩展 我们几年前推出了 iOS 平台的内容拦截器 这种扩展允许您配置强大的 规则来拦截资源负载 但今天要探讨的是 Safari 浏览器网页扩展 它们是去年 随 macOS Big Sur 一同推出的 今年秋季引入到了 iOS 15 和 iPadOS 15 这种扩展利用了 可在其他浏览器中运行 且深受我们用户喜爱 的网页技术 是 App Store 上最受欢迎的类别 并且像其他 app 一样容易安装 因为 Safari 浏览器网页扩展 是与 app 一同分发的 也就是说您可以享受到 在 App Store 上的优势 用户可以探索您的扩展 您也可轻松地提前销售扩展 甚至还能利用 app 内付款等 强大的功能来解锁 扩展的高级功能 或利用 TestFlight 来运行 beta 版程序 但是 您或许要说 “这固然很好 John 但我是 Web 开发者 不是 app 开发者” 我也一样！他们邀请我来这里 带您了解 Xcode 我们将从零开始构建一个新项目 也会提到 Safari 浏览器的 隐私保护权限模型 如何提交您的扩展 以及有关完成 App Review 审核流程的一些提示 我们从操作 Xcode 开始 为此 我们需要从 App Store 下载并安装这个 app 我将启动 App Store 在搜索栏中输入“Xcode” 它立即就会出现在屏幕中 接着 只需点按“获取”按钮 然后点按“安装” 下载尺寸比较大 需要一些时间 当您可以启动 Xcode 时 它会提示您安装命令行工具 如果跳过了安装 日后也可在“终端”中 从命令行轻松安装 您只需要键入“xcode-select” 并添加 install 旗标 系统就会启动安装过程 现在我的环境已经准备就绪 因此不必运行这个命令了 但您要确保安装这些工具 因为其中包含了一款重要工具 称为 Safari 浏览器 网页扩展转换工具 如果您编写过 适用于其他浏览器的网页扩展 或者您为 macOS 版 Safari 浏览器编写过扩展 并想升级为支持 iOS 版 Safari 浏览器 该工具会很有用处 我的文稿文件夹里有一个 简单的演示用网页扩展 这个 hello-world 扩展 是为其他浏览器编写的 其作用是在弹出式窗口中显示 一条“Hello World”信息 现在我可以使用转换工具 将它升级为支持 iOS 在“终端”中输入“xc” 在 Xcode 中 那就是“xcrun” 再输入 “safari-web-extension-converter” 以及项目的路径 如果您有为 macOS 版 Safari 浏览器编写的扩展 也可使用转换工具进行升级 只要输入“xcrun safari-web-extension-converter” 并添加 rebuild-project 旗标 再加上 macOS 扩展的路径 我们来实际看看 对 Hello World 扩展 运行转换工具时会发生什么

按 Return 即可开始升级过程 它的实际作用是 将我们的扩展封装为 一个 app 项目 以便我们针对 iOS 和 macOS 进行编译和运行 暂时切回到“终端” 这里要指出的是 这条备注有一个警告 显示 iOS 扩展 需要非持久的后台页面 这很有帮助 因为它实际上提供了一个 待办事项清单供我们检查 确保我们的扩展支持 iOS 我们返回到 Xcode 中 这个扩展已基本就绪 后台脚本已设置为 以非持久方式运行 我们只需要告诉 Safari 浏览器 按照这种方式运行它 若要使它支持 iOS 只需编辑清单文件 在 background 部分中 添加 persistent 键 将值设为 false 这样就可以了！ 我们来尝试在模拟器中运行一下 我将使用 Build Targets 菜单 并选择 iPhone 13 Pro 现在我已安装了许多模拟器 但您可能需要使用 Add Additional Simulators 下载您要在其中进行测试的模拟器 我将选择 iPhone 13 Pro 并点按 Build and Run 按钮 看起来像播放按钮的那个 这将构建我们的 app 并在模拟器中启动它 您可在状态栏的右上角 查看其状态 现在切换到模拟器 我需要等待 app 完成安装并启动

启动之后 我可以切换到“设置”app 找到“Safari 浏览器”部分 再轻点“扩展” 然后开启我们的 Hello World 扩展 现在到 Safari 浏览器中试验 启动 Safari 浏览器 并轻点“大小”菜单 那里可以找到 Hello World 扩展 我可以轻点这个扩展 它会提示授予权限 稍后我会详细讨论这一点 但现在 我将选择“允许 1 天” 这就好了 “Hello World!”信息 显示在弹出式窗口中 转换为其他浏览器编写的 网页扩展就是这么简单 我想到了一个为 Open Graph 元数据 构建预览的项目 这些元数据也用于在 Twitter 等 社交媒体网站上显示预览 我们已经有了网页的精美图像 标题和描述 所以我想构建一个 可以使用弹出式出窗口 来预览这些数据的扩展 这就是我们今天所要构建的内容 首先在 Xcode 中新建一个项目 在 Multiplatform 下选择 Safari Extension App 然后点按 Next 对于产品名称 我将使用“Open Graph Preview” 里面已使用反向域名惯例 填充了团队名称和组织标识符 语言保留为 Swift 再点按 Next 现在需要提供项目存储位置 存储到桌面即可 我将保持开启 “Create Git repository on Mac” 我喜欢内建版本控制 点按 Create 这将从模板生成 我们需要的项目 在继续操作之前 我想简略介绍一下 Xcode 窗口的左侧是导航边栏 里面整理了项目的所有资源 中间是主编辑器 内含您在导航器边栏中选择的文件 其右侧是检查器边栏 会根据您在编辑的文件而变化 我们不需要使用导航器边栏 因此我会将它隐藏起来 让工作空间变得更大一些 现在来看看构成 新的 Safari 浏览器 网页扩展项目的文件 导航器边栏顶部是项目文件 选择此文件后 会在项目的配置选项屏幕中 打开主编辑器 其下方是 Shared (App) 文件夹 内含 app 启动屏幕的资源 点按 Resources 文件夹 旁边的开合三角 您会看到里面就是网页资源 实际上就是一个可以 编辑的 HTML 文件 借助模板 您可以轻松地自定标记 样式和脚本 Shared (Extensions) 文件夹中 包含扩展的所有资源 展开 Resources 文件夹后 您会看到网页扩展的所有熟悉文件 包括清单、后台脚本 内容脚本和弹出式窗口文件 iOS (App) 和 macOS (App) 文件夹 包含特定于平台的资源 其下方是 iOS (Extension) 和 macOS (Extension) 文件夹 包含适用于这些平台的扩展相关资源 在这个项目中 我们不必操心这些 我将把它们放在一边 因为我们的所有工作都会在 Shared (Extension) 文件中进行 我们从清单文件开始 您可以看到模板提供了 启动项目所需的一切 包括从项目信息填充 名称和描述 在这下方 它指定了一些默认图标 您要记得为项目提供 自己的图标

这里提供了后台脚本 您可以看到它已设置为 以非持久方式运行后台脚本 目前对于这个项目 我们其实不需要后台脚本 因此我将从清单文件中 删除此条目并将后台脚本本身 删除后移入废纸篓中 接下来设置内容脚本 这里声明了 JavaScript 文件 以及可注入它的网站的域名模式 我希望此工具在用户有需要的 任何网站上都可用 因此我会将这里的 example.com 更改为星号 以便其能匹配任何域名 在这下方 它声明了浏览器操作部分 我们将定义一个“popup”文件 以及一组默认的工具栏图标 这里依然要记得为项目提供 自己的图标 最后是 permissions 键 我将添加 activeTab 作为我们要使用的权限 为何是 activeTab？ 很高兴您问到这个问题

我们来快速看看 扩展可以使用的各种权限 Safari 浏览器中的扩展模式 已设置为由用户掌控 只有在用户互动后才会运行 因此第一次使用时会显示 标记来帮助指导用户 权限是按各个网站来授予的 也就是说 Safari 浏览器设置 和偏好设置中会显示网站权限 以便用户进行控制 目前需要我们留意的权限类型有四种 我们来逐一介绍一下 第一种权限是脚本注入权限 此权限允许将 JavaScript 乃至样式表注入到用户浏览的页面中 具体要看 matches 键中 列出的网站域名 当用户浏览的网站与 matches 键中的模式匹配时 扩展注入脚本会在工具栏中显示标记 用户需要点按扩展才能启用它 它会一直待在那里 等待用户启用 下一种权限是隐式权限 清单文件中声明了 多种不同的隐式权限 我在这里着重介绍的第一种权限 是非敏感的 它不需要任何额外的特权 而第二种则是敏感的权限 因为它们具有网站标识数据 这是我们的一种用户隐私保护方法 当您调用 API 时 它会等待回调和数据 用户与扩展交互后会看到提示 他们可在大约一分钟内回应 在他们批准之后 回调会得到执行 数据也会返回 获得批准的所有操作 都会马上得到执行 下一种权限是显式权限 之所以称为显式 是因为扩展本身会索取权限 提示始终会以模态方式显示 不会添加标记 因为索取权限的是 扩展本身而不是用户 最后一种权限是活跃标签页权限 这是一种特殊情形 此时如果您不想显示提醒 可以使用活跃标签页 用户需要通过工具栏与扩展交互 或者在 Mac 上 他们可以使用键盘快捷键 或上下文菜单 这将为当前标签页中的当前域名 授予标签页权限 这也是我们今天要使用的权限 现在来继续谈谈如何编写内容脚本 内容脚本模板 设置为发送和侦听信息 现在我们不需要从内容脚本发送信息 而是需要侦听信息 内容脚本需要做的第一件事是 从用户浏览的页面 抓取 Open Graph 元数据 然后我们可以使用 简单的 DOM API 在正确的 meta 标记中 查找 OG 标题、描述和图像 那么扩展具体是如何运行的 用户将轻点扩展来打开弹出式窗口 弹出式窗口脚本负责在 内容脚本中查询当前页面的 Open Graph 数据 在这个侦听器回调中 我们要侦听带有关键词的信息 如果收到的信息不含关键词 那么不会执行任何操作 实际上这里会返回空值 但若收到了含有关键词的信息 我们会发回 meta 标记中的数据 内容脚本中需要做的就是这些 现在来看看设置弹出式窗口 先从弹出式窗口 HTML 文件开始 您可以看到这里 右侧显示了弹出式窗口的 样式表和 JavaScript Web 开发者会感觉得心应手 对于此文件中的标记 我们只需为标题、描述和图像预览 设置一些占位符元素 用于标题、描述和图像的 占位符元素已经设置好了

接下来我们将对弹出式窗口的 样式表做一些调整 这里只需要做几个细微调整 以便在所有平台上都可正常显示 最后只需要为图像设置 一个反应灵敏的设计布局 以填充空白并保持宽高比 最后一步 我们来到了扩展的核心 编辑弹出式窗口脚本 首先我们需要抓取 对弹出式窗口 HTML 文件中 定义的占位符元素的引用 接下来需要将信息发送至内容脚本 为此我们需要查询活跃标签页 要查询当前窗口中的活跃标签页 我们要使用 tabs.query API 在 tabs.query API 中 可以按照当前窗口中的 活跃标签页进行筛选 得到正确的标签页后 就可以发送信息了 在发送信息时 将传递当前的标签页 ID 这当然也包括我们的关键词 在收到回复时 只需要使用数据 来更新占位符元素 这就好了！ 我们来尝试在模拟器中运行这个扩展 仍然是从 Target 菜单中 选择 iPhone 13 Pro 模拟器 点按 Build and Run 按钮 以启动流程 切换到模拟器中 我们在这里等待 app 启动 启动之后 就能在“设置”app 中 启用这个新扩展了 我们来切换到“设置”中 再滚动到“Safari 浏览器” 然后轻点“扩展” 在 Open Graph Preview 下 可以开启这个开关 现在启动 Safari 浏览器 轻点“大小”菜单 此菜单中会包含 Open Graph Preview 轻点这个选项时 我会收到内容脚本的权限请求 我将选择“允许 1 天” 好了 我们有了此页面的 Open Graph 数据预览 我们在另一个页面中进行尝试 仍然是在“大小”菜单中 轻点 Open Graph Preview 和“允许 1 天” 好了 但不太对劲 不应该有无法显示的图像 看看这里出了什么问题 可以使用 Safari 浏览器中的 网页检查器 如果还没有启用 可前往 Safari 浏览器的“偏好设置” 在“高级”标签下启用 “在菜单栏中显示‘开发’菜单” 然后在“开发”菜单中 您可以对来自模拟器的 内容选择网页检查器 操作完毕后 就能轻松发现图像没有载入 如果 URL 错误 问题可能源自于内容 我们再对 webkit.org 打开另一个网页检查器

现在可以搜索 og meta 标记数据 这里可以发现 我们有了标题 也有了描述 但是缺少了图像 那便是原因所在 我们有一个未定义情形等待处理 返回到 Xcode 中 我们只需要处理 那个未定义情形就好 现在可以再次尝试运行 点按 Build and Run 按钮 点按 Replace 以在模拟器中 将它替换掉 在模拟器中启动后 就能回到 Safari 浏览器中 再次尝试

在“大小”菜单中选择 Open Graph Preview 就可以了 完美！ 它将显示标题和描述 但我们要确保它在没有 图像的页面上正常运行 结果确是如此 完美！ 放到在模拟器中运行是对多种设备 进行测试的绝佳方法 但最好还是在真实设备上测试 我的手边有一台 iPhone 返回到 Xcode 中 选择 Target 菜单 再选择 iPhone 现在构建并运行 然后在这台设备上启动

在设备上运行并启动后 需要在“设置”中启用它 我们切回到“设置”app 依次轻点“Safari 浏览器”、“扩展” 和 Open Graph Preview 以打开其开关 再次启动 Safari 浏览器 轻点“大小”菜单 看到所需扩展后 轻点这个扩展 和“允许 1 天” 可以完美运行 我们再测试几个页面 确保所有情况都正常运行 在 developer.apple.com 上 没有提示需要额外权限 因为这是 apple.com 域的一部分 我们试一试 webkit.org

这里再次轻点“大小”菜单 和 Open Graph Preview 这时会显示提示 因为这是一个不同的网站 完美！ 再测试一个含有图像的帖子 依次轻点“大小”菜单 Open Graph Preview 完美！ 非常好 我们的 app 和扩展在模拟器中 和真实设备上都能正常运行 可以说我们已准备好 将它提交到 App Store 了 提交之前要快速处理一个细节 在项目设置中 选择您的 iOS app 目标 确保设置一个 app 类别 我将选择 Developer Tools 接下来 在 Product 菜单中 选择 Archive 与构建过程相似 您会在状态栏右侧看到进度 准备就绪后 选择您准备提交的构建归档 再点按 Distribute App 按钮 在助理中的分发方式下 选择 App Store Connect 并点按 Next 对于目的地 保留 Upload 并点按 Next 这时会开始 与 App Store Connect 通信 以准备 app 记录

这里可以检查名称并确保 SKU 与用于 App Store Connect 帐户中其他 app 的 SKU 不同 现在点按 Next 按钮 它会开始准备我们的 app 记录以供审核 不过这里首先提供了一些分发选项 供您从中选取 它们都非常有用 我会保留不动 然后点按 Next 当然要保留为 Automatically manage signing 然后点按 Next 现在我们可以检查 app 内容 和扩展内容了 满意之后点按 Upload 在等待上传完成时 我们来快速看一些有关 完成 App Store 审核的提示 首先要确保自己是项目中 使用的所有代码以及任何内容 图像或其他素材资源的所有者 确保拥有或能够证明 对调用的所有 API 或 JavaScript 框架的权限 还要记得提供自定图标 并为 app 取一个独特名称 帮助它在 App Store 上脱颖而出 另外不要光用表情符号装饰网页 最好的网页扩展 也就是可入选精选推荐的那些 都是能够给用户带来一些价值的 如果您写的是 适用于其他浏览器的 任何网上付款或捐助代码 您需要将它停用 以进行 App Store 审核 扩展的前期销售不难 在 App Store 中 也非常流行 我们来检查上传过程 上传已经成功完成 很棒 现在到 Safari 浏览器中 我可以登录 App Store Connect 并点按“我的 App”以查看 刚才创建的新 app 记录 点按 Open Graph Preview 我可以为 App Store 提供 一些补充信息 您要为 app 提供一些预览图像 然后在“推广文本”下 提供一些有关此版本中 新增功能的描述信息 在“描述”下 您可以完整地介绍这个扩展 可为用户提供的功能 然后您还可以提供一些关键词 注意一百字符限制 您需要做到精准 还要提供页面专用的 URL 供用户用来获取扩展的支持 另外也可附上营销页面的地址 然后使用上传工具 选择 app 的正确上传项 填写了所有栏位后 可以点按“提交以供审核”按钮 来开始 App Review 流程 构建和提交 Safari 浏览器 网页扩展就是这么简单 建议您同时提交 iOS 和 和 MacOS 版的扩展 并查阅与本讲座相关的资源 欢迎您提交反馈 我们很乐意了解您的想法 您可以使用反馈助理来提交错误 或提出功能请求 感谢观看