跳转到主要内容

​
概述

当您的网站启用 Web SDK 时，OneSignal 会在浏览器的开发者工具控制台中提供详细的错误消息。 在故障排除之前，请仔细检查 Web SDK 设置 以确保：
  • OneSignal JavaScript 代码片段放置在您网站的 <head> 中。
  • Service worker 文件正确放置在根目录并可通过 HTTPS 访问。
按照以下步骤调试常见问题并验证您的集成是否正常工作。

​
初始故障排除步骤

1

在干净的浏览器配置文件中测试

在新的浏览器配置文件中打开您的网站。
  • 使用最新版本的 Chrome 或 Firefox。
  • 推送在隐身/私人/访客模式下不工作。
  • 检查支持的浏览器列表。
2

打开浏览器开发者工具

按 F12 键、右键单击并选择”检查”或导航到 查看 > 开发者 > JavaScript 控制台来启动开发者控制台。
3

尝试订阅并观察错误

尝试订阅您的网站并检查控制台是否有错误。然后将错误与下面的列表进行匹配以获得指导。

打开浏览器的开发者工具并检查错误

​
常见错误消息和解决方案

​
Service Worker 错误（403、404）

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

Service worker 安装错误示例

如果您看到 403 或 404 service worker 错误，您的 service worker 文件可能被阻止、重定向或丢失。
  • 确认文件可用性
    • 在浏览器中访问 service worker 文件 URL。您可以在 OneSignal 仪表板 设置 > 推送和应用内 > Web 中找到路径。
    • 示例路径：
      • https://yoursite.com/OneSignalSDKWorker.js
      • https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
    • 如果使用 WordPress，路径是：
      • https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js
  • 如果这些返回 403/404 或重定向，您的推送设置将无法工作。
  • 文件名区分大小写且必须可公开访问。
查看 Service Worker 设置指南 以确认正确设置。

​
不支持的 MIME 类型

  • 您的 service worker 必须以 application/javascript 格式提供。
  • 使用其他 MIME 类型（例如 text/html）提供文件会导致注册失败。

Service worker 中的 MIME 类型错误

​
不允许重定向

  • OneSignal SDK 文件不得重定向。
  • 它们必须托管在与您的网站相同的源上（不能使用 CDN 或代理域）。

控制台中的重定向错误

​
Web Push 配置只能在正确的站点源上使用

  • 您当前的域名与 OneSignal 仪表板中配置的网站 URL 不匹配。
  • 协议、域名和子域名必须完全匹配。

站点源不匹配错误

​
OneSignal 已经被定义

  • SDK 被多次初始化，通常由将 WordPress 插件设置与手动代码相结合引起。

重复 SDK 初始化错误

​
移动网页推送故障排除

iOS - 有关要求，请参阅 iOS 上的 Safari Web Push。 Android - Web push 在使用支持浏览器的 Android 移动设备上自动工作。
  1. 在移动设备上测试之前，首先确保您的网站在桌面上正常工作。
  2. 您可能已经在 Android web 上订阅，但我们的仪表板不会区分移动 web 订阅者和桌面 web 订阅者。Android web 订阅者在”订阅”页面的设备列中显示为 Linux armv8l。
  3. 检查浏览器应用程序中是否启用了通知。例如，在 Chrome 中，在您的 Android 设置 > 应用程序管理器 > Chrome 中。确保选中”显示通知”。
  4. 清除缓存。如果您的移动端浏览器缓存已满，这可能不允许进一步提示或订阅。
  5. 一些用户报告说，卸载并重新安装浏览器应用程序修复了提示不显示的问题。

​
Safari 故障排除

  1. 在 Safari 配置中设置的站点 URL 必须与您访问站点时看到的完全一致。例如，如果您在浏览器中看到 https://www.yoursite.com，那么您必须将此添加到设置字段中。www 和非 www 站点是不同的源。
  2. Safari 12.1+ 创建了一个新规则，即用户必须在站点上执行某些操作才能收到提示
您必须在 Safari 上使用滑动提示。这就是为什么如果您使用我们的典型设置，滑动提示总是在原生提示之前显示。 如果您只想使用原生浏览器提示，您需要设置自己的触发器来检测用户操作。然后调用我们的 Web SDK 方法来触发提示。
  1. 最后，尝试清除缓存并重置推送权限，以首次用户的身份查看您的站点并尝试重新订阅。

​
Safari 图标或站点名称未更改

由于 Safari 的自定义 web push 实现，您的站点名称和图标图像被视为下载并本地存储在用户计算机上的静态资源。新的站点名称和新图像不会更新或下载。 不幸的是，任何使用这些旧资源订阅的用户都需要清除缓存并重置推送权限并返回站点重新订阅。

​
清除缓存并重置推送权限

有关更多详细信息，请参阅清除缓存并重置推送权限。

​
使用浏览器开发者工具调试

浏览器的开发者工具可用于与网页上的 web SDK 交互，并启用日志记录或轻松向自己发送测试通知。
1

访问浏览器开发者工具控制台

访问开发者控制台

桌面调试：
  • Chrome：右键单击页面，点击检查，然后点击弹出窗口的控制台标签。
  • Firefox：右键单击页面，点击检查元素，然后点击弹出窗口的控制台标签。
  • Safari：转到 Safari → 偏好设置 → 高级，确保选中在菜单栏中显示开发菜单。然后，在您的网页上右键单击，点击检查元素，并点击弹出窗口的控制台标签。
Android 调试：
  • Android 上的 Chrome：启用 USB 调试，将设备连接到计算机，并在桌面 Chrome 浏览器中使用 chrome://inspect#devices 访问开发工具。
  • Android 上的 Firefox：启用 USB 调试，将设备连接到计算机，并在桌面 Firefox 浏览器中使用 about:debugging 访问开发工具。
2

启用 Web SDK 日志记录

现在您应该能够在开发者工具控制台中运行命令。执行以下代码：
OneSignal.Debug.setLogLevel('trace');
您应该看到 undefined 作为结果。如果您看到：
未捕获的引用错误：OneSignal 未定义(…) ReferenceError: OneSignal 未定义
那么 OneSignal 在您的网页上不活跃，或者您需要切换到 top 框架上下文（请参见上面的截图）。现在我们的 web SDK 的调试日志已启用，请关闭标签页并打开一个新标签页到同一页面（刷新页面不足以触发我们的某些 SDK 事件）。您应该在控制台中看到大量输出。

详细 SDK 日志的控制台

您始终可以通过输入此代码来禁用此附加日志记录：
OneSignal.Debug.setLogLevel('warn');
3

检查您是否已订阅

在控制台中运行：
function getUserInfo() {
	console.log('getUserInfo()');
	Promise.all([
		OneSignal.Notifications.permission,
		OneSignal.User.PushSubscription.id,
		OneSignal.User.PushSubscription.token,
		OneSignal.User.PushSubscription.optedIn,
		OneSignal.context.serviceWorkerManager.getActiveState(),
	])
		.then(
			([
				isSubscribed,
				subscriptionId,
				pushToken,
        optedIn,
				serviceWorkerActive,
			]) => {
        console.log('当前页面的 URL 是什么？', location.href);
         console.log(
					"是否注册了活跃的 service worker？（在 Safari 上应该是 false，否则应该是 'OneSignal Worker'）？",
					serviceWorkerActive
				);
        console.log('')
        console.log('Are you subscribed, in the browser?', isSubscribed)
        console.log('Are you opted-in, in OneSignal?' , optedIn);
				console.log('');
				console.log('What is your OneSignal Subscription ID?', subscriptionId);
				console.log('What is your Push Token?', pushToken);

			}
		)
		.catch(e => {
			console.error('确定推送是否启用时出现问题：', e);
		});
}
getUserInfo();
根据您是否已订阅，您应该看到类似以下内容：
当前页面的 URL 是什么？ http://localhost:8080/
是否注册了活跃的 service worker？（在 Safari 上应该是 false，否则应该是 'OneSignal Worker'）？ OneSignal Worker

Are you subscribed, in the browser? true
Are you opted-in, in OneSignal? true

What is your OneSignal Subscription ID? 22ff6b0d-60e1-469d-b667-005274204322
What is your Push Token? https://fcm.googleapis.com/fcm/send/drKvxiBc9Eo:APA91bFoa88bzkuudYFmuyNb8uIA60dI44SnBbXi0_4GAYa2Ln07XzrOs1-k5KVxrwKf8oVxBvzIXVN-44bamCRkaQ6cFODy7-8slGgnV3i2OqS3EgYrzU6VcO1KZaBHacsZhqvWqIRv
4

给自己发送测试通知

仅当您已订阅时（请参见上一节），您可以向自己发送测试通知。有关详细信息，请参阅查找和设置测试订阅。

​
调试未收到 Chrome 通知的问题

注意： 请按顺序完成这些步骤。
1

按照上面的步骤 1-4 尝试接收测试通知

  • 对于步骤 #3，您是否已订阅？如果没有，请在此停止，按照这些特定说明完全清除您的站点数据，然后重新订阅您的站点以接收通知。之后再次运行步骤 #3 以验证您实际上已订阅。在遵循清除站点数据说明时，请记住关闭您站点的所有标签页或重启浏览器，因为 Chrome 会阻止访问站点的存储，直到关闭该站点的所有现有标签页。
  • 对于步骤 #4，您是否收到了测试通知？如果收到了，您就完成了！
2

检查 OneSignal 仪表板中的投递页面

如果您已订阅但没有收到测试通知，请访问您的 OneSignal 仪表板投递页面，查看您发送给自己的测试通知是否显示在顶部。
3

使用 chrome://gcm-internals 检查消息投递

如果您已订阅、没有收到测试通知，但您看到消息已被投递（绿色显示），请在 Chrome 中打开 chrome://gcm-internals。点击左上角的”开始记录”按钮。确保您看到”连接状态：已连接”。保持打开状态并向自己发送推送（按照上面的步骤 #4 向自己发送测试通知）。如果您收到了，您应该在”接收消息日志”中看到一些东西。

GCM 内部日志记录

  • 如果您没有看到”数据消息已接收”，那么您的 Chrome 浏览器根本没有接收到通知。请在支持中告知我们这一点。
  • 如果您看到”数据消息已接收”但仍然没有收到通知，请继续执行步骤 #4。
4

使用 chrome://serviceworker-internals 调试 Service Worker

访问 chrome://serviceworker-internals。搜索 Scope: https://your-site.com。点击 检查，或者 开始 -> 检查，如下所示。将出现 Chrome 开发者工具弹窗。

检查 service worker

在我们的 service worker 的 Chrome 开发者工具弹窗中，点击 控制台 标签，并运行 OneSignalWorker.log.trace();。它应该返回 undefined。来自我们 service worker 的任何消息现在应该出现在此弹窗中。
5

捕获控制台输出并联系支持

从 service worker 的开发工具弹窗切换回主页的开发者工具控制台（在步骤 2 中使用的同一个）。 向自己发送另一个测试通知。如果您仍然看不到通知，请查看控制台输出中的任何新错误或消息。 要与支持人员分享此信息：
  • 在控制台内右键单击。
  • 选择 另存为… 导出日志文件。
  • 附加此文件并联系我们的聊天支持以获得进一步帮助。
需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：
  • 您遇到的问题详情以及复现步骤（如有）
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID（如适用）
  • 您在 OneSignal 控制台中测试的消息 URL（如适用）
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助！