要求
- 一个裸React Native 应用。对于管理的 Expo 应用,请使用 Expo SDK 设置
- React Native 0.71+(本指南使用 0.78.2)
- 已配置的 OneSignal 应用和平台
- 带有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
- 带有 iOS 12+、iPadOS 12+ 的设备或运行 iOS 16.2+ 的 Xcode 模拟器
- CocoaPods 1.16.2+
- 安装了 Google Play 商店(服务)的 Android 7.0+ 设备或模拟器
配置您的 OneSignal 应用和平台
推送通知所需设置 要开始使用 OneSignal 发送推送通知,您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。如果您的组织已有 OneSignal 账户,请要求邀请您为管理员角色以配置应用。否则,请注册免费账户以开始使用。
配置 OneSignal 应用的分步说明。
配置 OneSignal 应用的分步说明。
您可以在单个 OneSignal 应用下管理多个平台(iOS、Android、华为、Amazon、Web)。
配置平台凭据
根据您的平台按照提示操作:
- Android:设置 Firebase 凭据
- iOS:p8 令牌(推荐) 或 p12 证书
- Amazon:生成 API 密钥
- 华为:授权 OneSignal
SDK 设置
1. 添加 SDK
将react-native-onesignal 包添加到您的项目中。
2. 初始化 SDK
在您的App.tsx、App.js 或 index.js 文件中使用提供的方法初始化 OneSignal。
将 YOUR_APP_ID 替换为您在 OneSignal 仪表板 设置 > 密钥和 ID 中找到的 OneSignal 应用 ID。
如果您无法访问 OneSignal 应用,请要求您的 团队成员 邀请您。
App.tsx
Android 设置
确保您的 OneSignal 应用已使用您的 Firebase 凭据 为 Android 平台进行配置。 设置您的通知图标以匹配您的应用品牌。如果跳过此步骤,推送通知将显示默认的铃铛图标。 为 Android 构建 此时,您应该能够在物理 Android 设备或模拟器上无问题地构建和运行您的应用。确认您的 Android 构建正常工作后:
- 如果适用,继续进行 iOS 设置。
- 或者跳转到测试 OneSignal SDK 集成。
iOS 设置
确保您的 OneSignal 应用已使用 p8 令牌(推荐) 或 p12 证书 为 iOS 平台进行配置。 按照以下步骤向您的 iOS 应用添加推送通知,包括对徽章、确认送达 和图像的支持。1. 向应用目标添加推送通知功能
推送通知功能 允许您的应用注册推送令牌并接收通知。- 在 Xcode 中打开您的应用的
.xcworkspace文件。 - 选择 您的应用目标 > 签名和功能
- 点击 + 功能 并添加 推送通知 功能

2. 向应用目标添加后台模式功能
这使您的应用能够在推送通知到达时在后台唤醒。- 添加后台模式功能
- 启用 远程通知

3. 将应用目标添加到应用组
应用组 允许您的应用和通知服务扩展之间进行数据共享。这是确认送达和徽章功能所必需的。- 如果您尚未配置应用组
- 如果您已有应用组
- 添加 应用组 功能
- 在应用组功能中点击 +
- 添加格式为
group.your_bundle_id.onesignal的新容器 ID
- 保留 group. 和 .onesignal 前缀和后缀。将
your_bundle_id替换为您应用的包标识符。 - 例如,包标识符
com.onesignal.MyApp,将具有容器名称group.com.onesignal.MyApp.onesignal。

4. 添加通知服务扩展
通知服务扩展 (NSE) 启用丰富通知和确认送达分析功能。- 在 Xcode 中:File > New > Target…
- 选择 Notification Service Extension,然后点击 Next。
- 将产品名称设置为
OneSignalNotificationServiceExtension并按 Finish。 - 在激活方案提示上按 Don’t Activate。



如果您使用的是 CocoaPods,请同时在您的 Podfile 中设置部署版本。

5. 将 NSE 目标添加到应用组
使用您在第 3 步中添加的相同应用组 ID。- 转到 OneSignalNotificationServiceExtension > Signing & Capabilities
- 添加 App Groups
- 添加完全相同的组 ID

6. 更新 NSE 代码
- 导航到 OneSignalNotificationServiceExtension 文件夹
- 将
NotificationService.swift或NotificationService.m文件的内容替换为以下内容:


7. 将 OneSignal 添加到 NSE 目标
更新您的ios/Podfile 以包含:
shell
常见的 pod install 错误
您可能会遇到以下错误,以下是解决方法。ArgumentError - \[Xcodeproj] 无法找到对象版本 `70` 的兼容性版本字符串。
ArgumentError - \[Xcodeproj] 无法找到对象版本 `70` 的兼容性版本字符串。
CocoaPods 依赖
xcodeproj Ruby gem 来读取您的 Xcode 项目文件。截至目前,最新的 xcodeproj 版本不识别 Xcode 16 引入的对象版本 70。因此,当 CocoaPods 尝试打开您的 .xcodeproj 文件时,它会因为这个错误而崩溃。- 关闭 Xcode。
- 导航到您项目的
ios/<your-app>.xcodeproj/project.pbxproj文件。 - 更改这一行:
objectVersion = 70; - 将其替换为:
objectVersion = 55; - 保存、关闭,并重新运行
cd ios pod install cd ..
为 iOS 构建
现在您应该能够在真实的 iOS 设备或 iOS 模拟器(iOS 16.2+)上构建和运行您的应用。常见的 iOS 构建错误
循环内部... 构建可能产生不可靠的结果。
循环内部... 构建可能产生不可靠的结果。
在使用 Xcode 15+ 构建时,您可能会看到这个错误,这是由于影响跨平台系统的默认配置更改所致。

- 在 Xcode 中打开您的
.xcworkspace文件夹并导航到 您的应用目标 > Build Phases。 - 您应该有一个名为 “Embed Foundation Extensions” 或 “Embed App Extensions” 的阶段。
- 拖放并将此构建阶段移动到 “Run Script” 之上。
- 构建和运行您的应用。错误应该得到解决。


PBXGroup 错误
PBXGroup 错误
RuntimeError -
PBXGroup attempted to initialize an object with unknown ISA PBXFileSystemSynchronizedRootGroup from attributes: {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}- 找到错误中在 “path” 下列出的文件夹
- 在 Xcode 项目侧边栏中,右键单击该文件夹
- 选择 Convert to Group


在确认您的 iOS 构建正常工作后,请继续进行 测试 OneSignal SDK 集成。
测试 OneSignal SDK 集成
本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。检查移动端订阅
刷新 OneSignal 控制台的订阅页面。
设置测试订阅
测试订阅有助于在发送消息之前测试推送通知。通过 API 发送测试推送
获取您的应用 API 密钥和应用 ID。
在您的 OneSignal 控制台中,转到 设置 > 密钥和 ID。
发送应用内消息
应用内消息让您可以在用户使用您的应用时与他们进行沟通。在设备上关闭或将您的应用切换到后台。
这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中,当用户在应用处于后台或关闭至少 30 秒后重新打开应用时,会开始一个新会话。更多详情,请参阅我们的应用内消息如何显示指南。
用户识别
之前,我们演示了如何创建移动端订阅。现在我们将扩展到使用 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。




添加电子邮件和/或短信订阅
之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。- 使用
addEmail方法创建电子邮件订阅。 - 使用
addSms方法创建短信订阅。

多渠道沟通的最佳实践
- 在添加电子邮件或短信订阅之前获得明确同意。
- 向用户解释每个沟通渠道的好处。
- 提供渠道偏好,让用户可以选择他们偏好的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管控方法:setConsentRequired(true):阻止数据收集直到获得同意。setConsentGiven(true):一旦获得同意即启用数据收集。
提示推送权限
不要在应用打开时立即调用requestPermission(),而是采取更策略性的方法。在请求权限之前,使用应用内消息解释推送通知的价值。
有关最佳实践和实现细节,请参阅我们的提示推送权限指南。
监听推送、用户和应用内事件
使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。推送通知事件
addClickListener():检测通知被点击时。对深度链接有帮助。addForegroundLifecycleListener():控制通知在前台的行为方式。
用户状态变化
addObserver()用于用户状态:检测外部 ID 设置时。addPermissionObserver():跟踪用户与原生推送权限提示的特定交互。addObserver()用于推送订阅:跟踪推送订阅状态变化时。
应用内消息事件
addClickListener():处理应用内点击操作。适用于深度链接或跟踪事件。addLifecycleListener():跟踪应用内消息的完整生命周期(显示、点击、关闭等)。
高级设置和功能
探索更多功能以增强您的集成:移动端 SDK 设置和参考
通过查看移动端推送设置指南,确保您已启用所有关键功能。 有关可用方法和配置选项的完整详细信息,请访问移动端 SDK 参考。恭喜!您已成功完成移动端 SDK 设置指南。
需要帮助?与我们的支持团队聊天或发送邮件至
support@onesignal.com请包含以下信息:- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息
















