概述
本指南解释了如何将 OneSignal 推送通知集成到 ReactJS 或 NextJS 应用程序中。它涵盖了从安装到配置以及服务工作器管理的所有内容。要求
- 已配置的 OneSignal 应用程序和平台。请参阅 Web 推送设置 开始使用。
安装
选择您首选的包管理器:初始化
导入 OneSignal 服务并在根组件中初始化它。 将YOUR_APP_ID
替换为在 Keys & IDs 中找到的 OneSignal 应用程序 ID。
自定义初始化选项
您可以使用附加的init
参数 自定义初始化。
服务工作器设置
如果您还没有这样做,您需要下载 OneSignal Service Worker 文件添加到您的站点。OneSignalSDKWorker.js
文件必须能够公开访问。您可以将其放在 public
目录、顶级根目录或子目录中。但是,如果您将文件放在子目录中和/或为您的站点有另一个服务工作器,请确保指定路径。有关详细信息,请参阅 OneSignal Service Worker。
选项 | 描述 |
---|---|
serviceWorkerParam | 由 OneSignal 工作器控制的范围。**建议:**使用自定义子路径(例如,"/onesignal/" )。 |
serviceWorkerPath | 托管的 OneSignal 服务工作器文件的路径(例如,"onesignal/OneSignalSDKWorker.js" )。必须可公开访问。 |
在这里查看完整的工作示例:React + OneSignal 示例
托管工作器
- 公共根目录(默认):
/OneSignalSDKWorker.js
- 自定义文件夹(推荐):例如,
/onesignal/OneSignalSDKWorker.js
,如上一步中设置的。
验证服务工作器托管
在您的浏览器中访问该路径以确认其可访问。 如果您使用的是根目录:重要注意事项
- 避免在开发中重复初始化
- 在开发环境中测试时,您可能会看到 OneSignal SDK 初始化两次,这可能会导致控制台错误。
- 这是由于
<React.StrictMode>
导致效果在开发中运行两次。要解决此问题,请在开发期间从您的根组件中删除<React.StrictMode>
。
严格模式只影响开发——它不会影响生产构建。
测试 OneSignal SDK 集成
本指南帮助您验证 OneSignal SDK 集成是否正常工作,通过测试推送通知和订阅注册。检查网页推送订阅
1
在测试设备上启动您的网站。
- 测试时使用 Chrome、Firefox、Edge 或 Safari。
- 请勿使用无痕或隐私浏览模式。 用户无法在这些模式下订阅推送通知。
- 提示应根据您的权限提示配置出现。
- 在原生提示上点击允许以订阅推送通知。

网页推送原生权限提示
2
检查您的 OneSignal 控制台
检查 OneSignal 控制台:
- 前往受众 > 订阅。
- 您应该看到状态为已订阅的新条目。

控制台显示订阅状态为'已订阅'
您已成功创建了网页推送订阅。
当用户首次订阅您网站的推送通知时,将创建网页推送订阅。
设置测试订阅
测试订阅有助于在发送消息前测试推送通知。1
添加到测试订阅。
在控制台中,在订阅旁边,点击选项(三个点)按钮并选择添加到测试订阅。

将设备添加到测试订阅
2
命名您的订阅。
命名订阅,以便您后续在测试订阅选项卡中轻松识别您的设备。

控制台显示'命名您的订阅'字段
3
创建测试用户细分。
前往受众 > 细分 > 新建细分。
4
命名细分。
将细分命名为
Test Users
(名称很重要,因为后续会用到)。5
添加测试用户过滤器并点击创建细分。

使用测试用户过滤器创建'测试用户'细分
您已成功创建了测试用户细分。
现在我们可以测试向这个单独设备和测试用户组发送消息。
通过 API 发送测试推送
1
获取您的应用 API 密钥和应用 ID。
在您的 OneSignal 控制台中,前往设置 > 密钥和 ID。
2
更新提供的代码。
在下面的代码中将
YOUR_APP_API_KEY
和 YOUR_APP_ID
替换为您的实际密钥。这段代码使用了我们之前创建的 Test Users
细分。3
运行代码。
在您的终端中运行代码。
4
检查图片和确认投递。
如果所有设置步骤都成功完成,测试订阅应该会收到通知。
仅 Chrome 支持图片。图片在收缩的通知视图中显示很小。展开通知以查看完整图片。

Chrome macOS 上带图片的展开推送通知
5
检查确认投递。
在您的控制台中,前往投递 > 已发送消息,然后点击消息查看统计数据。您应该看到已确认统计数据,表示设备收到了推送。
如果您使用专业版或更高版本,滚动到受众活动查看订阅级别确认:
Safari 不支持确认投递。

显示确认投递的投递统计数据

受众活动中设备级别的确认投递
您已成功通过我们的 API 向细分发送了通知。
需要帮助?请与
support@onesignal.com
联系,并提供以下信息:- 将 API 请求和响应复制粘贴到
.txt
文件中 - 您的订阅 ID
- 包含 OneSignal 代码的网站 URL
用户识别
之前,我们演示了如何创建网页推送订阅。现在我们将扩展到使用 OneSignal SDK 识别所有订阅(包括推送、电子邮件和短信)中的用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件追踪,帮助您统一并跨平台互动用户。分配外部 ID
使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码中一致地识别用户。这确保您的消息在渠道和第三方系统中保持统一(对集成尤其重要)。 每次您的应用识别用户时,使用我们 SDK 的login
方法设置外部 ID。
OneSignal 为订阅(订阅 ID)和用户(OneSignal ID)生成唯一的只读 ID。当用户在不同设备上下载您的应用、订阅您的网站和/或在应用外提供电子邮件地址和电话号码时,将创建新的订阅。强烈建议通过我们的 SDK 设置外部 ID,以在用户的所有订阅中识别用户,无论订阅是如何创建的。
添加数据标签
标签是字符串数据的键值对,您可以使用它们存储用户属性(如username
、role
或偏好设置)和事件(如 purchase_date
、game_level
或用户交互)。标签为高级消息个性化和细分提供支持,允许更高级的使用场景。
当应用中发生事件时,使用我们 SDK 的addTag
和 addTags
方法设置标签。
在这个例子中,用户达到了 6 级,可通过名为 current_level
的标签识别,值设置为 6
。

OneSignal 中一个用户资料,包含名为'current_level'的标签,设置为'6'

细分编辑器显示针对 current_level 值大于 4 且小于 10 的用户的细分

显示针对 5-10 级细分的个性化消息推送通知的截图
添加电子邮件和/或短信订阅
之前我们看到了我们的 SDK 如何创建网页推送订阅来发送推送。您也可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。- 使用
addEmail
方法创建电子邮件订阅。 - 使用
addSms
方法创建短信订阅。

通过外部 ID 统一的具有推送、电子邮件和短信订阅的用户资料
多渠道沟通的最佳实践
- 在添加电子邮件或短信订阅之前获得明确同意。
- 向用户解释每个沟通渠道的好处。
- 提供渠道偏好设置,以便用户可以选择他们喜欢的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意门控方法:setConsentRequired(true)
:在给予同意之前阻止数据收集。setConsentGiven(true)
:一旦获得同意就允许数据收集。
监听推送、用户和应用内事件
使用 SDK 监听器对用户操作和状态变化做出反应。 SDK 为您提供了多个事件监听器可以钩入。查看我们的SDK 参考指南了解更多详情。推送通知事件
用户状态变化
- 用户状态变化事件监听器:检测外部 ID 何时被设置。
- 权限观察器:追踪用户与原生推送权限提示的特定交互。
- 推送订阅变化观察器:追踪推送订阅状态何时变化。
高级设置和功能
探索更多功能以增强您的集成:Web SDK 设置和参考
通过查看Web 推送设置指南,确保您已启用所有关键功能。 有关可用方法和配置选项的完整详情,请访问Web SDK 参考。恭喜!您已成功完成 Web SDK 设置指南。
需要帮助?与我们的支持团队聊天或发送邮件至
support@onesignal.com
请包含以下信息:- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息