> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS 网页推送设置

> 在 iOS 和 iPadOS 设备上启用网页推送通知的完整指南，包括清单文件设置、用户引导策略以及 Safari、Chrome 和 Edge 浏览器的实施最佳实践。

export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
  const baseUrl = 'https://onesignal.github.io/sdk-releases';
  const buildUrl = (theme, sdkFilter, viewMode) => {
    const url = new URL(baseUrl);
    const params = new URLSearchParams();
    if (theme) {
      params.set('theme', theme);
    }
    if (sdkFilter) {
      params.set('sdk', sdkFilter);
    }
    if (viewMode) {
      params.set('viewMode', viewMode);
    }
    if (params.toString()) {
      url.search = params.toString();
    }
    return url.toString();
  };
  const detectTheme = () => {
    if (document.documentElement.classList.contains('dark')) {
      return 'dark';
    }
    return 'light';
  };
  const [theme, setTheme] = useState('light');
  const [iframeSrc, setIframeSrc] = useState(() => {
    const initialTheme = detectTheme();
    return buildUrl(initialTheme, sdkFilter, viewMode);
  });
  useEffect(() => {
    const currentTheme = detectTheme();
    setTheme(currentTheme);
    setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleThemeChange = () => {
      const newTheme = detectTheme();
      setTheme(newTheme);
      setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
    };
    if (mediaQuery.addEventListener) {
      mediaQuery.addEventListener('change', handleThemeChange);
    } else {
      mediaQuery.addListener(handleThemeChange);
    }
    window.addEventListener('storage', handleThemeChange);
    const observer = new MutationObserver(handleThemeChange);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ['class', 'data-theme']
    });
    return () => {
      if (mediaQuery.removeEventListener) {
        mediaQuery.removeEventListener('change', handleThemeChange);
      } else {
        mediaQuery.removeListener(handleThemeChange);
      }
      window.removeEventListener('storage', handleThemeChange);
      observer.disconnect();
    };
  }, [sdkFilter, viewMode]);
  const getIframeHeight = () => {
    if (viewMode === 'table') {
      return '450';
    }
    if (viewMode === 'mini') {
      return '170';
    }
    return '800';
  };
  const iframeHeight = height || getIframeHeight();
  return <Frame {...frameProps}>
      <iframe src={iframeSrc} width="100%" height={iframeHeight} frameBorder="0" style={{
    border: "none"
  }} title="SDK Releases" key={iframeSrc} />
    </Frame>;
};

<SdkReleasesIframe sdkFilter="react,vue,vue3,angular,wordpress" viewMode="table" height="380" />

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

<Frame caption="移动设备上网页推送通知示例。">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/2477862-iOS_push-doc.jpg?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=86aed6cdbed6645e568a644ac725f414" width="806" height="929" data-path="images/docs/2477862-iOS_push-doc.jpg" />
</Frame>

***

## 2025 年重要更新

**跨浏览器支持**：网页推送通知现在在 iOS/iPadOS 16.4+ 的所有主流浏览器上都能正常工作，包括 Safari、Chrome 和 Edge。

**iOS 17+ 改进**：由于默认启用了相关 API，增强了实施效果，让用户更容易使用网页推送。

**可靠性考虑**：一些开发者报告了偶发的可靠性问题，即 iOS 网页推送通知可能初期正常工作，但随后意外停止。请监控您的通知推送成功率，并制定备用参与策略。

***

## 要求

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

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

如果您的网站已经是一个[渐进式网页应用 (PWA)](https://onesignal.com/blog/what-is-a-pwa/)，则不需要额外的站点更新。使用 [Chrome DevTools 中的 Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/#devtools) 来审计您的站点是否符合 PWA 标准。

***

## 设置

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

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

#### 必需的清单字段

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

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

#### 示例清单文件

```json theme={null}
{
  "$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"
}
```

#### 实施步骤

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

```html theme={null}
<link rel="manifest" href="/manifest.json"/>
```

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

<Note>
  使用 [SimiCart Manifest Generator](https://www.simicart.com/manifest-generator.html/) 等工具快速创建清单文件，或使用 [Manifest Tester](https://manifesttester.com/) 验证现有文件。
</Note>

### 2. 添加 OneSignal service worker

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

### 3. 配置权限提示

您 [Web SDK 设置](./web-sdk-setup) 中的现有[网页权限提示](./permission-requests)在 iOS 设备上**仅在用户将您的站点添加到主屏幕并从那里打开后**才能正常工作。这是 Apple 的设计要求。

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

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

#### 必需的用户流程

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

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

<Frame caption="在 iOS 上将网站添加到主屏幕">
  <img src="https://mintcdn.com/onesignal/2iWYYuHf1gqm06bv/images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg?fit=max&auto=format&n=2iWYYuHf1gqm06bv&q=85&s=54cb44f40d70397099b32375a3e97683" width="1346" height="736" data-path="images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg" />
</Frame>

#### 用户引导策略

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

* **网站横幅**：在移动 Apple 设备上专门显示横幅，解释通知的价值并提供逐步说明。

* **可视化指南**：使用截图和箭头向用户确切展示点击位置。

* **时机**：在用户对您的内容表现出参与度后再展示指导。

#### 实施示例

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

<Frame caption="提示用户添加到主屏幕的横幅示例">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/0b97752-image.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=bfec43a31639c25a6eab85961334a8bd" width="2055" height="1257" data-path="images/docs/0b97752-image.png" />
</Frame>

<Frame caption="逐步可视化指导">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4e970c1-image.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=04aef274f934dd44f34eaa8bd7e37360" width="2055" height="1257" data-path="images/docs/4e970c1-image.png" />
</Frame>

<Frame caption="以益处为主的消息">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/208b123-image.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=c8bd38cfb229c68500a9260b8b6e4b33" width="2055" height="1257" data-path="images/docs/208b123-image.png" />
</Frame>

<Frame caption="具有视觉提示的清晰行动号召">
  <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7ec125a-image.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=c532cb02bcde365092a6bc001beaaf06" width="2055" height="1257" data-path="images/docs/7ec125a-image.png" />
</Frame>

#### 开源解决方案

考虑实施这个受欢迎的开源横幅解决方案：

**GitHub 项目**：[add-to-home-screen by rajatsehgal](https://github.com/rajatsehgal/add-to-home-screen)

<Frame caption="来自 rajatsehgal 开源项目的添加到主屏幕横幅提示示例。">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=ccc678721ffc636fa5ddb4a71efb7ed0" width="1149" height="2142" data-path="images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg" />
</Frame>

更多横幅示例和最佳实践可在 [web.dev](https://web.dev/promote-install/) 查看。

### 5. 测试和验证

#### 清单文件测试

1. **可访问性检查**：导航到 `https://yoursite.com/manifest.json` 以确保公开可访问性
2. **浏览器开发者工具**：
   * 打开 Chrome DevTools (F12)
   * 转到“应用程序”选项卡 → 清单
   * 查看任何错误或警告
3. **在线验证器**：
   * [Manifest Tester](https://manifesttester.com/)
   * [Redirection.io Validator](https://redirection.io/tools/web-app-manifest/validator)
   * [ValidBot Manifest Wizard](https://www.validbot.com/tools/app-manifest-wizard.php)

#### 端到端推送通知测试

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

#### 重要测试说明

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

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

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

**常见问题检查**：

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

***

## 故障排除

**清单不加载**：检查文件路径、HTTPS 要求和服务器上的 MIME 类型配置。

**图标不显示**：验证图标文件可访问性和清单中的正确尺寸规格。

**权限提示不出现**：确保用户通过主屏幕应用访问站点并首先点击了互动元素。

**通知未推送**：验证 OneSignal service worker 是否正确安装，并检查浏览器控制台是否有错误。

***

## 下一步

<Check>
  您现在已准备好发送通知！继续查看[推送](./push)文档或使用我们的[创建消息](/reference/create-message) API 开始通过网页推送通知与您的 iOS 用户互动。
</Check>

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

***
