iOS 网页推送设置

Apple 开始在 iOS 和 iPadOS 16.4+ 上支持为添加到用户主屏幕的网页应用提供推送通知。此功能在 Safari、Chrome 和 Edge 浏览器上都能正常工作，为以网页为主的公司带来了新的参与机会。这份综合指南涵盖了成功实施 iOS 网页推送通知所需的一切内容。

移动设备上网页推送通知示例。

2025 年重要更新

跨浏览器支持：网页推送通知现在在 iOS/iPadOS 16.4+ 的所有主流浏览器上都能正常工作，包括 Safari、Chrome 和 Edge。 iOS 17+ 改进：由于默认启用了相关 API，增强了实施效果，让用户更容易使用网页推送。 可靠性考虑：一些开发者报告了偶发的可靠性问题，即 iOS 网页推送通知可能初期正常工作，但随后意外停止。请监控您的通知推送成功率，并制定备用参与策略。

要求

iOS/iPadOS 版本：16.4 或更高版本
HTTPS 源：具备响应式设计的安全连接
网页应用清单：具有正确设置的有效 manifest.json 文件
主屏幕安装：必须从任何支持的浏览器将网页应用添加到用户主屏幕
用户主动操作：在权限提示出现之前，用户必须先与您的站点进行交互
OneSignal Service Worker：通知推送所必需

渐进式网页应用 (PWA) 检查

如果您的网站已经是一个渐进式网页应用 (PWA)，则不需要额外的站点更新。使用 Chrome DevTools 中的 Lighthouse 来审计您的站点是否符合 PWA 标准。

设置

1. 创建您的网页应用清单

网页应用清单 (manifest.json) 是一个 JSON 文件，定义了您的网页应用在用户设备上安装时的外观和行为。对于 iOS 网页推送，这个文件是必须的。

必需的清单字段

您的 manifest.json 必须包含这些必要字段：

$schema （推荐）：用于验证和 IDE 支持的 JSON schema URL
name （必需）：显示给用户的完整应用名称
display （必需）：为了 iOS 兼容性，必须设置为 "standalone" 或 "fullscreen"
start_url （必需）：应用启动时的入口 URL
icons （必需）：包含多种尺寸的图标对象数组
id （推荐）：允许多个应用实例的唯一标识符

示例清单文件

{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "OneSignal Manifest Example",
  "short_name": "OS Manifest",
  "display": "standalone",
  "start_url": "/",
  "theme_color": "#E54B4D",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-256x256.png", "sizes": "256x256", "type": "image/png" },
    { "src": "/icon-384x384.png", "sizes": "384x384", "type": "image/png" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "id": "?homescreen=1"
}

实施步骤

文件放置：将 manifest.json 放在您网站的根目录中
HTML 集成：将此链接标签添加到所有页面的 <head> 部分：

<link rel="manifest" href="/manifest.json"/>

图标准备：创建多种尺寸的高质量 PNG 图标（推荐 192x192、256x256、384x384、512x512 像素）

使用 SimiCart Manifest Generator 等工具快速创建清单文件，或使用 Manifest Tester 验证现有文件。

2. 添加 OneSignal service worker

如果您已经完成了我们的 Web SDK 设置并且可以在其他浏览器上接收网页推送通知，则此步骤已完成。请查看 OneSignal Service Worker 文档获取详细的设置说明。

3. 配置权限提示

您 Web SDK 设置中的现有网页权限提示在 iOS 设备上仅在用户将您的站点添加到主屏幕并从那里打开后才能正常工作。这是 Apple 的设计要求。

4. 引导用户“添加到主屏幕”

与根据您的设置显示权限提示的桌面或 Android 设备不同，iOS 需要您必须促进的特定用户流程。

必需的用户流程

用户必须完成这些步骤才能接收通知：

在 iOS/iPadOS 16.4+ 上使用 Safari、Chrome 或 Edge 访问您的网站
点击浏览器的分享按钮
选择添加到主屏幕选项
将应用保存到其设备
从主屏幕打开应用（而不是从浏览器）
与您的订阅按钮交互以触发原生权限提示

在 iOS 上将网站添加到主屏幕

用户引导策略

由于这个过程不太直观，请通过以下方式实施清晰的指导：

网站横幅：在移动 Apple 设备上专门显示横幅，解释通知的价值并提供逐步说明。
可视化指南：使用截图和箭头向用户确切展示点击位置。
时机：在用户对您的内容表现出参与度后再展示指导。

实施示例

以下是来自实际应用的有效方法：

提示用户添加到主屏幕的横幅示例

逐步可视化指导

以益处为主的消息

具有视觉提示的清晰行动号召

开源解决方案

考虑实施这个受欢迎的开源横幅解决方案： GitHub 项目：add-to-home-screen by rajatsehgal

来自 rajatsehgal 开源项目的添加到主屏幕横幅提示示例。

更多横幅示例和最佳实践可在 web.dev 查看。

5. 测试和验证

清单文件测试

可访问性检查：导航到 https://yoursite.com/manifest.json 以确保公开可访问性
浏览器开发者工具：
- 打开 Chrome DevTools (F12)
- 转到“应用程序”选项卡 → 清单
- 查看任何错误或警告
在线验证器：

端到端推送通知测试

在 iOS 16.4+ 设备上使用 Safari、Chrome 或 Edge 访问您的网站
点击浏览器的分享按钮
选择添加到主屏幕
将应用保存到您的设备
从主屏幕打开应用（关键步骤）
触发您的订阅按钮 - 应显示原生权限提示
授予权限并测试通知推送

重要测试说明

重新测试要求：要在同一设备上再次测试：

从主屏幕删除应用
清除浏览器缓存（设置 > Safari/Chrome/Edge > 清除缓存）
重复此过程

权限被拒绝恢复：如果权限被拒绝，必须删除并重新添加主屏幕应用，权限提示才会再次出现。 常见问题检查：

确保 display 字段为 "standalone" 或 "fullscreen"
验证所有图标路径可访问
确认清单以正确的 MIME 类型 (application/manifest+json) 提供服务
测试 CORS 错误

故障排除

清单不加载：检查文件路径、HTTPS 要求和服务器上的 MIME 类型配置。 图标不显示：验证图标文件可访问性和清单中的正确尺寸规格。 权限提示不出现：确保用户通过主屏幕应用访问站点并首先点击了互动元素。 通知未推送：验证 OneSignal service worker 是否正确安装，并检查浏览器控制台是否有错误。

下一步

您现在已准备好发送通知！继续查看推送文档或使用我们的创建消息 API 开始通过网页推送通知与您的 iOS 用户互动。

为了持续成功，请监控您的 iOS 网页推送性能指标，并考虑实施渐进式增强策略，优雅处理 iOS 用户所需的额外步骤，同时为其他平台提供无缝体验。

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

iOS 网页推送设置

2025 年重要更新