跳转到主要内容

​
概述

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

​
浏览器兼容性

用户可能会看到网页权限提示,但无法在隐身、隐私或访客浏览器模式下订阅推送通知。
BrowserWindowsmacOSAndroidiOS
Chrome✅✅✅✅ ¹
Firefox✅✅✅✅ ¹
Safari 10+❌✅❌✅ ¹
Microsoft Edge✅✅✅✅ ¹
Opera ²✅✅✅✅ ¹
Samsung Internet ²❌❌✅✅ ¹
Yandex ²✅✅✅✅ ¹
UC Browser ²✅❌✅✅ ¹
Internet Explorer❌❌❌❌
DuckDuckGo❌❌❌❌
¹ iOS 需要安装 Web 应用(参见 iOS 网页推送设置)² 基于 Chromium 的浏览器在 OneSignal 分析中显示为 “Chrome”

​
设备通知设置

您设备的通知设置和专注模式(勿扰模式、低电量等)可能会阻止通知的显示。您也可能已为浏览器等特定应用关闭了通知。请检查以下内容以确保您的设备已配置为接收通知。
  1. 选择开始 > 设置 > 通知和操作 > 从应用和其他发送者获取通知
  2. 确保您的站点和浏览器也已启用。

Windows 10 通知设置

Windows 11 通知设置:
  1. 选择开始 > 设置 > 系统 > 通知

Windows 11 通知设置

  1. 打开通知
  2. 关闭勿扰模式(在测试时,禁用此选项后推送才会显示)
  3. 向下滚动至来自应用和其他发送者的通知
  1. 确保您的浏览器已打开。

Windows 11 通知设置浏览器列表

​
提示显示问题

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

确认已配置提示

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

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

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

检查浏览器的通知设置

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

Chrome 通知设置

在此示例中:
  • 用户已选择”不允许站点发送通知”,这将阻止原生权限提示显示。必须显示”站点可以请求发送通知”才能允许原生权限提示显示。
  • 用户已将 https://yoursite.com 添加到”不允许发送通知”列表中,这将阻止原生权限提示显示。必须从列表中删除此项才能允许原生权限提示显示。
特定浏览器文档:
  • Chrome - 此页面说明如何通过转到设置 > 隐私和安全性 > 网站设置 > 通知来管理 Chrome 中的通知,您可以在其中控制默认行为并管理各个网站的权限。
  • Firefox - 本指南涵盖 Firefox 的网页推送通知,说明如何通过设置 > 隐私和安全性 > 通知管理通知权限,以及如何通过地址栏的站点信息图标控制特定站点的权限。
  • Safari - 此 Apple 指南说明如何通过 Safari > 偏好设置 > 网站 > 通知在 Mac 上自定义 Safari 通知,您可以在其中管理哪些站点可以发送通知并通过系统偏好设置控制通知行为。
  • Edge - 本文详细说明如何通过导航到设置 > 隐私、搜索和服务 > 站点权限 > 通知来管理 Edge 通知,或者通过点击地址栏中的站点信息图标。
4

不满足 iOS/iPadOS 要求。

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

​
故障排除步骤

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

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

浏览器的开发者工具可用于在您的网页上与我们的 Web SDK 交互，并启用日志记录以检查错误。
  • Chrome：右键单击页面，单击检查，然后单击弹出窗口的控制台选项卡。
  • Firefox：右键单击页面，单击检查元素，然后单击弹出窗口的控制台选项卡。
  • Safari：转到 Safari → 偏好设置 → 高级，确保选中在菜单栏中显示”开发”菜单。然后在您的网页上右键单击，单击检查元素，然后单击弹出窗口的控制台选项卡。

桌面开发者工具控制台

2

验证 OneSignal 已在您的页面上加载并初始化

在控制台中运行：
JavaScript
  OneSignal.initialized
结果的含义：
  • true ✅ - OneSignal 已初始化并准备就绪。继续下一步。
  • false ⚠️ - OneSignal 已加载但尚未完成初始化。稍等片刻然后重试。
  • Uncaught ReferenceError: OneSignal is not defined ❌ 验证 OneSignal JavaScript 代码段是否在您站点的 <head> 部分中，检查脚本是否在您尝试使用 OneSignal 方法之前加载。查看 Web SDK 设置指南
  • OneSignal is already defined SDK 在同一页面上被初始化多次。删除一个初始化方法。如果使用 WordPress 插件，请从主题文件中删除任何手动 OneSignal 代码。
3

启用 Web SDK 日志记录

现在您可以在开发者工具控制台中运行命令。执行以下代码：
JavaScript
  OneSignal.Debug.setLogLevel('trace');
  • 您应该看到 undefined 作为结果。
  • 关闭选项卡并打开同一页面的新选项卡。仅刷新不会触发所有 SDK 初始化事件。
  • 您将开始在控制台中看到 OneSignal SDK 日志。

包含详细 SDK 日志的控制台

​
配置错误

OneSignal 初始化后，您可能会遇到以下错误：
Error: SDK already initialized

SDK 重复初始化错误

这意味着什么： 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 和控制面板配置之间匹配。

​
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）。

service worker 安装错误示例

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

service worker 中的 MIME 类型错误

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

控制台中的重定向错误

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

查找您的 service worker 路径

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

直接在浏览器中访问 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 或您配置的文件名。某些服务器会自动将文件名转换为小写。如果找不到文件，请考虑这一点。
3

验证文件是否加载

  • 您应该看到以下 JavaScript 代码：
    JavaScript
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
  • 此文件必须以 application/javascript 的 content-type 提供。
  • 此文件不能有重定向。文件必须托管在与您的站点相同的域上（不能使用 CDN 或代理域）
查看 Service Worker 设置指南以获取更详细的设置说明。

​
通知未显示

本节假设：
  1. 您已查看通知未显示：Web Push指南，了解通知可能无法在您的设备上显示的常见原因。
  2. 您看到了原生权限提示并单击了”允许”。如果您没有通过原生权限提示订阅，请参阅上面的提示显示问题。
如果上述条件为真，请按照以下步骤检查您的订阅 ID 并向自己发送推送通知：
1

获取您的订阅 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。

    用户信息示例

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

向自己发送通知

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

使用 Chrome 测试

如果您没有在 Chrome 中收到通知，请使用这些 Chrome 特定的诊断工具来识别问题。
  1. 在新标签页中，打开 chrome://gcm-internals。
  2. 单击左上角的”Start Recording”按钮。确保您看到”Connection State: CONNECTED”。
  3. 保持此页面打开状态，并向您的 Chrome web push 订阅发送另一个推送通知。
  4. 如果您收到了通知，您应该在”Receive Message Log”中看到一些内容。

GCM 内部日志记录

  • 如果您没有看到”Data msg received”，则说明您的 Chrome 浏览器根本没有收到通知。请在支持渠道告知我们这一情况。
  • 如果您看到”Data msg received”但仍未收到通知，请继续下一步。
  1. 在新标签页中打开 chrome://serviceworker-internals
  2. 搜索 Scope: https://your-site.com（将 your-site.com 替换为您的实际站点域名）。
  3. 单击 Inspect 或 Start -> Inspect。将出现 Chrome 开发者工具弹出窗口。

检查 service worker

  1. 在我们的 service worker 的 Chrome 开发者工具弹出窗口上，单击 Console 选项卡，然后运行 OneSignalWorker.log.trace();。它应该返回 undefined。我们的 service worker 发出的任何消息现在都应该出现在此弹出窗口中。
需要帮助？与我们的支持团队聊天或发送邮件至 [email protected]请包含以下信息：
  • 您遇到的问题详情以及复现步骤（如有）
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID（如适用）
  • 您在 OneSignal 控制台中测试的消息 URL（如适用）
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助！