> ## 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.
# 网页推送常见问题
> OneSignal 网页推送通知设置、要求、浏览器兼容性、域名更改以及为开发者和网站所有者排查常见问题的完整指南。
## 网页推送要求
您的网站必须满足以下所有条件才能使网页推送正常工作：
**所需的浏览器 API**
* [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
* [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
* [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
**安全性和连接**
* ✅ 仅限 HTTPS（具有有效的 SSL 证书）
* ✅ 已安装 OneSignal 的 [service worker](./onesignal-service-worker)
* ✅ 浏览器必须能够访问：
* 浏览器推送服务器（例如 FCM、Mozilla）
* `api.onesignal.com`
**用户状态**
* ✅ 用户已授予通知权限
* ❌ 不在隐身/私人/访客模式下
* ❌ 网站数据未被清除（删除订阅）
清除浏览器数据（cookie、网站存储）会自动取消用户的推送通知订阅。
### iOS/iPadOS 要求
要在 iOS 或 iPadOS 上接收推送：
* iOS 16.4+ 或 iPadOS 16.4+
* 网站必须添加到主屏幕并从那里打开
* 具有必需字段的有效 `manifest.json` 文件
* 用户必须在作为网页应用打开后接受通知权限
遵循 Apple 特定步骤在运行 iOS 16.4+ 的 iPhone 和 iPad 上启用网页推送。
***
## 浏览器和平台支持
### 按操作系统分类的浏览器兼容性
| 浏览器 | Windows PC | macOS | Android | iOS (iPhone, iPad) |
| :------------------------------------------------------------------------------: | :--------: | :----: | :-----: | :----------------: |
| [Chrome 50+](https://en.wikipedia.org/wiki/Google_Chrome) | **支持** | **支持** | **支持** | **支持** ¹ |
| [Firefox 47+](https://en.wikipedia.org/wiki/Firefox) | **支持** | **支持** | **支持** | **支持** ¹ |
| [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\)) | 不支持 | **支持** | 不支持 | **支持** ¹ |
| [Microsoft Edge 18+](https://en.wikipedia.org/wiki/Microsoft_Edge) ² | **支持** | **支持** | **支持** | **支持** ¹ |
| [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ² | **支持** | **支持** | **支持** | **支持** ¹ |
| [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² | 不支持 | 不支持 | **支持** | **支持** ¹ |
| [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ² | **支持** | **支持** | **支持** | **支持** ¹ |
| [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ² | **支持** | 不支持 | **支持** | **支持** ¹ |
| [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer) ³ | 不支持 | 不支持 | 不支持 | 不支持 |
| [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo) | 不支持 | 不支持 | 不支持 | 不支持 |
* ¹ iOS 需要安装网页应用（请参阅上面的 [iOS 网页推送设置](./web-push-for-ios) 要求）
* ² 基于 Chromium 的浏览器在 OneSignal 分析中显示为 "Chrome"
* ³ Internet Explorer 已弃用，不再接收更新
隐身模式、私人浏览模式和访客浏览器模式在任何平台上都**不**支持网页推送。
***
## 域名更改和迁移
### 了解浏览器源策略
出于安全原因，浏览器将网页推送订阅绑定到特定的[源（域名/网站 URL）](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)。**您不能在不同源之间转移订阅者** - 这是浏览器的限制，而不是 OneSignal 的限制。
**不同源包括：**
* HTTP vs HTTPS（例如 `http://mysite.com` → `https://mysite.com`）
* www vs 非-www（例如 `www.mysite.com` vs `mysite.com`）
* 不同域名/子域名（例如 `domain1.com` vs `domain2.com` 或 `sub1.domain.com` vs `sub2.domain.com`）
### 迁移选项
在更改您网站源时，请选择以下方法之一：
**最适合**：大多数域名更改，特别是当您希望进行干净迁移时
1. **为您的新域名创建新的 OneSignal 应用**
2. **双发送策略**：继续从旧应用发送，但将“启动 URL”设置为您的新域名
3. **渐进过渡**：
* 高频率发送者（每日 1+ 次通知）：2 周过渡期
* 中频率发送者（每周 2+ 次通知）：2 个月过渡期
4. **迁移通知**：在过渡开始和结束时发送 1-2 条消息，如“我们搬家了！访问我们的新网站以获取更新”
从两个应用发送相同消息将为订阅了两个应用的用户创建重复通知。
**最适合**：当您需要保持相同的 OneSignal 应用 ID 时
1. 使用[更新应用](/reference/update-an-app) API，包含：
* `name`：您的应用/网站名称
* `chrome_web_origin`：新网站 URL
* `chrome_web_default_notification_icon`：图标图像 URL
2. **删除旧订阅者**以防止重复：
* 创建群组：“设备类型为网页推送”
* [删除群组中的所有用户](./delete-users)
### HTTP 到 HTTPS 的升级
从 HTTP 升级到 HTTPS 会创建一个新的源。请遵循上述域名迁移步骤，因为浏览器将 HTTPS 网站视为与其 HTTP 版本完全分离的网站。
***
## 多个网站和子域名
### 单个应用的限制
由于浏览器的同源策略，您**不能**将一个 OneSignal 应用用于多个源，如：
* `https://mysite.com` 和 `https://www.mysite.com`
* `https://main.com` 和 `https://shop.main.com`
### 多个源的解决方案
* 仅在您的主域名上订阅用户
* 将其他源的用户重定向到主域名进行订阅
* 订阅后重定向回原始页面
* 为每个源创建单独的 OneSignal 应用
* 接受用户如果订阅了多个网站可能会接收到重复通知
***
### 语言支持场景
* 类似 `https://mysite.com/en/` 或 `https://mysite.com/es/` 的 URL
* 使用单个 OneSignal 应用
* 遵循[多语言提示指南](./permission-requests#faq)
* 实施[语言和本地化](./multi-language-messaging)
* 类似 `https://en.mysite.com` 或 `https://es.mysite.com` 的 URL
* 每个子域名都需要单独的 OneSignal 应用
***
## 高级配置
### 同一网站上的多个 OneSignal 应用
* **不推荐** - 会导致订阅冲突。
* **发生的情况**：OneSignal 会自动将用户重新订阅到最近访问的应用 ID，导致订阅者在应用之间跳转并创建许多未订阅的设备。
* **更好的方法**：使用[数据标签](./add-user-data-tags)在单个应用内对用户进行分组。
### 子文件夹网站
网页推送在源级别上运作。对于子文件夹中的网站（例如 `https://example.com/blog`），请使用主源 (`https://example.com`) 进行设置。
### 自行托管 SDK 文件
**强烈不推荐**。浏览器推送规范经常变化，OneSignal 会立即更新文件以保持兼容性。请使用您的网页推送设置中的 OneSignal CDN URL。
### 自定义初始化代码
自定义 `init` 代码仅适用于[自定义代码设置](./web-push-custom-code-setup)。
**典型设置或网站构建器用户**：自定义初始化代码将被 OneSignal SDK 忽略。如果您需要延迟初始化，请使用[隐私方法](./web-sdk-reference#privacy)。
***
## 开发和测试
### 本地环境测试
有关完整的本地测试设置，请参阅 [Web SDK 设置 > 本地测试](./web-sdk-setup#local-testing)。
### Service worker 集成
OneSignal 可以与现有的 service workers 和 PWA 并存工作。请参阅[集成多个 Service Workers](./onesignal-service-worker)获取实施详情。
***
## 推送垃圾邮件
推送通知不是为用于广告、垃圾邮件或欺骗性活动而设计的。
如果您的应用被检测为发送垃圾通知，浏览器可能会向您的用户发送“垃圾邮件警告”通知。
避免发送以下通知：
* 与用户不相关的内容
* 使用“广告”等字眼或链接到与应用无关的页面
* 不来自可信来源（例如您未关联的品牌）
更多信息请参阅[在 Chrome 中使用机器学习对抗不需要的通知](https://blog.chromium.org/2025/05/fighting-unwanted-notifications-with.html)。
如果您的应用被标记为垃圾邮件，您可以：
* 审查您的通知内容并删除任何可能被认为是垃圾邮件的内容。这包括：
* 标题或正文中的“广告”或“广告”字样
* 链接到与应用无关的页面
* 链接到不来自可信来源的页面（例如您未关联的品牌）
* 继续发送并监控进一步的报告。
***
## 故障排除
### 更新部署时机
* **Service Worker 文件**：24 小时缓存
* **Web SDK**：3 天缓存
在部署关键更新时请相应地制定计划。
### macOS Chrome 通知问题
对于 macOS Chrome 用户，请确保为**两者**都启用了通知：
1. **Google Chrome** 应用（Apple 菜单 > 设置 > 通知）
2. **Google Chrome Helper** 应用
如果两者都未启用，通知将不会出现在通知中心中。
### 设置后的下一步
1. **在您支持的浏览器和设备上进行彻底测试**
2. **为权限请求实施适当的错误处理**
3. **设置分析**来监控订阅率
4. **制定您的通知策略**以避免用户疲劳
5. **考虑对权限请求时机和消息进行 A/B 测试**
### 常见迁移陷阱
* **Browser data clearing** unsubscribes users automatically
* **Duplicate notifications** during dual-app transitions
* **iOS 需要安装 Web 应用**才能使用推送功能
* **私人/隐身模式**从不支持推送通知
* **Service workers 必须可在您网站的根目录或配置的子目录中访问**
***
## 下一步
* [Web SDK 设置](./web-sdk-setup)
* [Web SDK 参考](./web-sdk-reference)
***