Web SDK 故障排除

概述

本指南将指导您排除 OneSignal Web SDK 设置的故障。在继续之前，请查看 Web SDK 设置以确保您已完成所有步骤。 Web 推送似乎不工作的最常见原因实际上与您的浏览器和设备的通知设置有关：

浏览器兼容性

用户可能会看到网页权限提示,但无法在隐身、隐私或访客浏览器模式下订阅推送通知。

按操作系统的浏览器兼容性

Browser	Windows	macOS	Android	iOS
Chrome	✅	✅	✅	✅ ¹
Firefox	✅	✅	✅	✅ ¹
Safari 10+	❌	✅	❌	✅ ¹
Microsoft Edge	✅	✅	✅	✅ ¹
Opera ²	✅	✅	✅	✅ ¹
Samsung Internet ²	❌	❌	✅	✅ ¹
Yandex ²	✅	✅	✅	✅ ¹
UC Browser ²	✅	❌	✅	✅ ¹
Internet Explorer	❌	❌	❌	❌
DuckDuckGo	❌	❌	❌	❌

¹ iOS 需要安装 Web 应用(参见 iOS 网页推送设置)² 基于 Chromium 的浏览器在 OneSignal 分析中显示为 “Chrome”

设备通知设置

设备通知设置是Web推送通知无法显示的最常见原因。请在检查其他问题之前，先检查以下设置（包括勿扰模式、低电量等专注模式）。

请从下方标签页选择正确的操作系统。您应该看到 Windows、macOS、Android 和 iOS。

Windows 系统
macOS 系统
Android 系统
iOS 系统

Windows 10 通知设置

选择开始 > 设置 > 通知和操作 > 从应用和其他发送者获取通知
确保您的站点和浏览器也已启用。

Windows 11 通知设置:

选择开始 > 设置 > 系统 > 通知

打开通知
关闭勿扰模式（在测试时，禁用此选项后推送才会显示）
向下滚动到来自应用和其他发送者的通知

Windows 11 Settings showing the Notifications from apps and other senders list — Windows 11 来自应用和其他发送者的通知

确保您的浏览器已打开。

提示显示问题

以下是网页推送通知提示可能无法按预期显示的常见原因。

确认已配置提示

检查您的网页权限提示设置,以确保您已配置提示并了解不同的浏览器行为。例如,某些浏览器(如 Safari)需要用户操作(点击按钮)才能显示原生提示。有关每个浏览器的详细信息,请参阅我们的网页权限提示 > 原生权限提示部分。

检查浏览器兼容性、隐身模式、隐私浏览器或访客浏览器模式。

浏览器不允许用户在这些模式下订阅通知。这就是为什么滑动提示可能会显示,但原生权限提示不会显示的原因。确保您正在使用支持网页推送的浏览器和设备。

检查浏览器的通知设置

导航至浏览器的设置并检查”通知”权限设置。Chrome 示例:chrome://settings/content/notifications

在此示例中:

用户已选择”不允许站点发送通知”,这将阻止原生权限提示显示。必须显示”站点可以请求发送通知”才能允许原生权限提示显示。
用户已将 https://yoursite.com 添加到”不允许发送通知”列表中,这将阻止原生权限提示显示。必须从列表中删除此项才能允许原生权限提示显示。

特定浏览器文档:

Chrome - 此页面说明如何通过转到设置 > 隐私和安全性 > 网站设置 > 通知来管理 Chrome 中的通知,您可以在其中控制默认行为并管理各个网站的权限。
Firefox - 本指南涵盖 Firefox 的网页推送通知,说明如何通过设置 > 隐私和安全性 > 通知管理通知权限,以及如何通过地址栏的站点信息图标控制特定站点的权限。
Safari - 此 Apple 指南说明如何通过 Safari > 偏好设置 > 网站 > 通知在 Mac 上自定义 Safari 通知,您可以在其中管理哪些站点可以发送通知并通过系统偏好设置控制通知行为。
Edge - 本文详细说明如何通过导航到设置 > 隐私、搜索和服务 > 站点权限 > 通知来管理 Edge 通知,或者通过点击地址栏中的站点信息图标。

不满足 iOS/iPadOS 要求。

对于 iOS,需要满足一些额外要求才能提示用户订阅。更多信息请参阅 iOS/iPadOS 移动网页推送指南。

故障排除步骤

检查上述内容后，请按照以下步骤排除 OneSignal Web SDK 设置的故障。

打开浏览器开发者工具控制台

浏览器的开发者工具可用于在您的网页上与我们的 Web SDK 交互，并启用日志记录以检查错误。

Desktop
Android
iOS

Chrome：右键单击页面，单击检查，然后单击弹出窗口的控制台选项卡。
Firefox：右键单击页面，单击检查元素，然后单击弹出窗口的控制台选项卡。
Safari：转到 Safari → 偏好设置 → 高级，确保选中在菜单栏中显示”开发”菜单。然后在您的网页上右键单击，单击检查元素，然后单击弹出窗口的控制台选项卡。

Android 上的 Chrome：启用 USB 调试，将设备连接到计算机，并在桌面 Chrome 浏览器中使用 chrome://inspect#devices 访问开发者工具。
Android 上的 Firefox：启用 USB 调试，将设备连接到计算机，并在桌面 Firefox 浏览器中使用 about:debugging 访问开发者工具。

启用 Web SDK 日志记录

现在您可以在开发者工具控制台中运行命令。执行以下代码：

JavaScript

  OneSignal.Debug.setLogLevel('trace');

您应该看到 undefined 作为结果。
关闭选项卡并打开同一页面的新选项卡。仅刷新不会触发所有 SDK 初始化事件。
您将开始在控制台中看到 OneSignal SDK 日志。

配置错误

OneSignal 初始化后，您可能会遇到以下错误：

Error: SDK already initialized

这意味着什么： OneSignal Web SDK 的 init 代码被调用了多次，通常是由于将 WordPress 插件设置与手动代码结合使用，或意外多次添加 OneSignal init 代码造成的。 如何修复： 删除任何重复的 init 调用。如果使用 WordPress 插件，请从主题文件中删除任何手动 OneSignal 代码。

Error: Can only be used on: (OneSignal 控制面板中设置的 URL)

示例显示 OneSignal 控制面板中设置的 URL `http://127.0.0.1:5501` 不是您当前访问的站点源。

这意味着什么： 您当前访问的域名与 OneSignal 控制面板中配置的站点 URL 不匹配。 如何修复： 复制浏览器中的站点 URL 并将其粘贴到 OneSignal 控制面板的设置 > Push & In-app > Web > 站点 URL 配置中。确保它是使用以下格式的站点源：

协议： 必须是 https://（对于本地测试，请参阅Localhost 配置）
域名： example.com 与 www.example.com
子域名： app.example.com 与 example.com

这三个组件必须在您的实际站点 URL 和控制面板配置之间匹配。

Error: OneSignalSDK: The “My site is not fully HTTPS” option is no longer supported starting with version 16 (User Model) of the OneSignal SDK.

这意味着什么： 您的 OneSignal 控制面板配置为使用 HTTP 站点，而您可能已更新为使用 HTTPS。您的用户在使用 HTTP 或”我的站点不完全是 HTTPS”选项时订阅您的站点，实际上订阅的是我们以 https://your-label.os.tc 格式提供给您的子域名，而不是您的实际站点源。这是因为 HTTP 站点或无法托管 service worker 的网站不支持 web push。 如何修复： 您有 2 个选择，但两者都需要您的用户重新订阅，因为他们实际上订阅的是 os.tc 子域名。

创建一个新的 OneSignal 应用程序，并在 OneSignal init 代码中设置新的应用程序 ID。这样做的好处是您可以继续从旧的/原始 OneSignal 应用程序发送推送。发送尽可能多的通知，让您的用户知道站点已更新，他们应该回来再次订阅以继续获取更新。提供折扣或激励以重新订阅会有很大帮助。将”启动 URL”设置为登录页面，并为他们提供一个按钮以便轻松重新订阅，例如我们的铃铛提示、自定义链接提示或类别滑动提示。有关更多详细信息，请参阅权限提示。
如果您想保留相同的应用程序 ID，您需要使用我们的更新应用程序 API 将 chrome_web_origin 和 safari_site_origin 更新为您的 HTTPS 站点源。由于这些用户订阅的是 os.tc 子域名,他们在浏览器中没有为您的站点允许推送权限。浏览器不”知道”他们已订阅您的站点，因此他们将再次收到提示。如果他们再次订阅，他们将在同一浏览器上拥有 2 个到您站点的 web push 订阅，并将收到重复的通知。因此，我们建议删除所有当前的 web push 订阅者以防止他们收到重复的通知。在删除之前，发送几条通知，让他们知道站点已更新，他们应该再次订阅以继续获取更新。提供折扣或激励以重新订阅效果非常好。将”启动 URL”设置为登录页面,并为他们提供一个按钮以便轻松重新订阅，例如我们的铃铛提示、自定义链接提示或类别滑动提示。有关更多详细信息，请参阅权限提示。

Service worker 安装错误

如果您看到原生权限提示并单击”允许”，您可能会遇到以下 service worker 安装错误：

Y: Service Worker 注册失败。

[Service Worker 安装] 安装 service worker 失败 TypeError：无法为范围（‘https://your-site.com/’）使用脚本（‘https://your-site.com/...’）注册 ServiceWorker：获取脚本时收到错误的 HTTP 响应代码（404）。

[Service Worker 安装] 安装 service worker 失败 TypeError：无法为范围（‘https://www.yoursite.com/’）使用脚本（‘https://www.yoursite.com/...’）注册 ServiceWorker：获取脚本时收到错误的 HTTP 响应代码（403）。

脚本具有不受支持的 MIME 类型（‘当前 MIME 类型’）。 [Service Worker 安装] 安装 service worker 失败 SecurityError：无法为范围（‘https://your-site.com/‘）使用脚本（‘https://your-site.com/…’）注册 ServiceWorker：脚本具有不受支持的 MIME 类型（‘当前 MIME 类型’）。

[Service Worker 安装] 安装 service worker 失败 SecurityError：无法为范围（‘https://your-site.com/‘）使用脚本（‘https://your-site.com/…’）注册 ServiceWorker：脚本资源位于重定向之后，这是不允许的。

这意味着什么： 您的 service worker 文件配置不正确。 如何修复：

查找您的 service worker 路径

除非您指定自定义文件名或位置（如 Service Worker 设置指南中所述），否则我们的 SDK 会在站点的根目录中查找 OneSignalSDKWorker.js service worker 文件。确保您已配置正确的文件名、位置和范围，以便我们的 SDK 找到 service worker 文件。

直接在浏览器中访问 service worker 文件

根据您的配置，直接在浏览器中打开该文件。

如果您没有配置自定义位置，那么您应该在站点的根目录中看到 service worker 文件的 JavaScript 代码：https://yoursite.com/OneSignalSDKWorker.js
如果使用 WordPress，您应该在这里看到它：https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js
如果使用自定义位置，您应该在这里看到它：https://yoursite.com/your-custom-location/OneSignalSDKWorker.js

文件名区分大小写。确保使用 OneSignalSDKWorker.js 或您配置的文件名。某些服务器会自动将文件名转换为小写。如果找不到文件，请考虑这一点。

验证文件是否加载

您应该看到以下 JavaScript 代码：

JavaScript

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

此文件必须以 application/javascript 的 content-type 提供。
此文件不能有重定向。文件必须托管在与您的站点相同的域上（不能使用 CDN 或代理域）

查看 Service Worker 设置指南以获取更详细的设置说明。

通知未显示

本节假设：

您已查看通知未显示：Web Push指南，了解通知可能无法在您的设备上显示的常见原因。
您看到了原生权限提示并单击了”允许”。如果您没有通过原生权限提示订阅，请参阅上面的提示显示问题。

如果上述条件为真，请按照以下步骤检查您的订阅 ID 并向自己发送推送通知：

获取您的订阅 ID

在浏览器开发者工具控制台中运行以下代码：

JavaScript

  function getUserInfo() {
  	console.log('getUserInfo()');
  	Promise.all([
      OneSignal.Notifications.isPushSupported(),
  		OneSignal.Notifications.permission,
      OneSignal.User.PushSubscription.optedIn,
      OneSignal.User.PushSubscription.id
  	]).then(([
      isPushSupported,
      isSubscribed,
      isOptedIn,
      subscriptionId
    ]) => {
      console.log('The current URL of this page: ', location.href);
      console.log('Push is supported on this browser: ', isPushSupported);
      console.log('You are subscribed to notifications in the browser: ', isSubscribed);
      console.log('You are opted-in with OneSignal: ' , isOptedIn);
      console.log('Your OneSignal Subscription ID: ', subscriptionId);
    }).catch(e => {
      console.error('Error getting user info:', e);
    });
  }
  getUserInfo();

这将告诉您：

如果有任何混淆，您所在页面的 URL。
您当前使用的浏览器是否支持推送通知。
- true 表示浏览器支持推送通知。
- false 表示浏览器不支持推送通知。
您是否在浏览器中订阅了通知。
- true 表示您允许了此 URL 的推送权限。
- false 表示您没有允许或拒绝了此 URL 的推送权限。
您是否已在 OneSignal 中选择加入。
- true 表示您的订阅已在 OneSignal 中订阅推送通知。
- false 表示您的订阅未在 OneSignal 中订阅推送通知。检查您的站点上是否正在调用 optOut() 方法。
您的 OneSignal 订阅 ID。
- 保存此 ID 以备下一步使用。这是您将用于向自己发送推送通知的 ID。
用户信息示例

如果需要进一步帮助，请将此控制台数据保存到文本文件中并与我们的支持团队分享。

向自己发送通知

如果您已订阅通知、已在 OneSignal 中选择加入并拥有订阅 ID，则可以向自己发送通知。按照查找和设置测试订阅中的步骤将自己设置为测试者并向自己发送通知。

使用 Chrome 测试

如果您没有在 Chrome 中收到通知，请使用这些 Chrome 特定的诊断工具来识别问题。

在新标签页中，打开 chrome://gcm-internals。
单击左上角的”Start Recording”按钮。确保您看到”Connection State: CONNECTED”。
保持此页面打开状态，并向您的 Chrome web push 订阅发送另一个推送通知。
如果您收到了通知，您应该在”Receive Message Log”中看到一些内容。

如果您没有看到”Data msg received”，则说明您的 Chrome 浏览器根本没有收到通知。请在支持渠道告知我们这一情况。
如果您看到”Data msg received”但仍未收到通知，请继续下一步。

在新标签页中打开 chrome://serviceworker-internals
搜索 Scope: https://your-site.com（将 your-site.com 替换为您的实际站点域名）。
单击 Inspect 或 Start -> Inspect。将出现 Chrome 开发者工具弹出窗口。

在我们的 service worker 的 Chrome 开发者工具弹出窗口上，单击 Console 选项卡，然后运行 OneSignalWorker.log.trace();。它应该返回 undefined。我们的 service worker 发出的任何消息现在都应该出现在此弹出窗口中。

需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：

您遇到的问题详情以及复现步骤（如有）
您的 OneSignal 应用 ID
外部 ID 或订阅 ID（如适用）
您在 OneSignal 控制台中测试的消息 URL（如适用）
任何相关的日志或错误信息

我们很乐意为您提供帮助！

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

Web SDK 故障排除

概述

浏览器兼容性

设备通知设置

提示显示问题

故障排除步骤

配置错误

Service worker 安装错误

通知未显示

​概述

​浏览器兼容性

​设备通知设置

​提示显示问题

​故障排除步骤

​配置错误

​Service worker 安装错误

​通知未显示

概述

浏览器兼容性

设备通知设置

提示显示问题

故障排除步骤

配置错误

Service worker 安装错误

通知未显示