Skip to main content

概览

本指南解释了如何将 OneSignal 推送通知集成到 Ionic、Capacitor 或 Cordova 应用程序中。它涵盖了从安装到配置和服务工作器管理的所有内容。
正在构建 Capacitor 应用?我们强烈建议改用 Capacitor SDK 设置指南。仅当您的 Capacitor 项目必须使用 Cordova 插件以兼容现有 Cordova 代码时,才使用此 Cordova 设置。

要求

  • Cordova v10+(设置说明使用 v12)
  • 已配置的 OneSignal 应用和平台
iOS 要求
  • cordova-ios 8.0+
  • 具有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
  • iOS 12+、iPadOS 12+ 设备或运行 iOS 16.2+ 的 Xcode 模拟器
  • CocoaPods 1.16.2+
Android 要求
  • 安装了 Google Play Store(服务)的 Android 7.0+ 设备或模拟器
应用名称不应包含空格(例如,使用”MyApp”而不是”My App”)以避免构建问题

配置您的 OneSignal 应用和平台

使用您支持的平台配置您的 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。
如果您的组织已有 OneSignal 账户,请申请加入组织。否则,请注册免费账户以开始使用。
1

创建或选择您的应用

点击 新应用/网站 创建新应用,或在 设置 > 推送和应用内 中向现有应用添加平台。选择您要配置的平台,然后点击 下一步:配置您的平台
OneSignal 控制台显示包含组织名称、应用名称和频道选择的新应用设置流程

设置您的第一个 OneSignal 应用、组织和频道。

2

配置平台凭据

为您的平台输入凭据:输入您的凭据后点击 保存并继续
3

保存您的应用 ID 并安装 SDK

您的 应用 ID 显示在最终屏幕上。复制并保存它——初始化 SDK 时需要使用它。选择您的 SDK 平台,然后按照设置指南操作。
OneSignal 控制台显示设置完成后的应用 ID 和团队邀请选项

保存您的应用 ID 并邀请其他团队成员。


SDK 设置

1. 添加 SDK

onesignal-cordova-plugin 包添加到您的项目中。

iOS 原生依赖项

onesignal-cordova-plugin 5.5.0 开始,使用 cordova-ios 8 或更高版本的 Cordova iOS 应用可以通过 Swift Package Manager (SPM) 解析 OneSignal 的原生 iOS 依赖项。较旧的 Cordova iOS 应用会继续通过 OneSignalCordovaDependencies 使用 CocoaPods。 使用此 Cordova 插件并启用 SPM 的 Capacitor 应用需要 Capacitor 8.4.0 或更高版本,以便 Capacitor 可以读取插件根目录中的 Package.swift。对于新的 Capacitor iOS 项目,请使用 npx cap add ios --packagemanager SPM 创建原生平台,然后在安装插件后运行 npx cap sync ios

可选:禁用位置模块

onesignal-cordova-plugin 5.4.0 开始,如果您的应用不使用 OneSignal.Location,您可以从 Android、iOS CocoaPods 和 iOS Swift Package Manager 构建中排除 OneSignal 的原生位置模块。 在安装插件或同步原生平台之前设置 ONESIGNAL_DISABLE_LOCATION=true。该值不区分大小写。您也可以将其设置为 1。对于 iOS Swift Package Manager,请在实际 Xcode 构建过程中保持该标志已设置,以便 Package.swift 在禁用位置模块的情况下求值。
禁用位置模块后,对 OneSignal.Location 的调用会被忽略。OneSignal.Location.isShared() 会解析为 false

在扩展目标中使用模块化 CocoaPods 子规格

如果您的 iOS Podfile 在通知服务扩展或其他扩展目标中显式添加了 OneSignalXCFramework,请使用模块化子规格。聚合声明 pod 'OneSignalXCFramework' 会解析为 OneSignalComplete,其中包含 OneSignalLocation,从而使 ONESIGNAL_DISABLE_LOCATION 失效。
可选:如果您的应用还有 Live Activity widget 扩展,请仅添加其所需的子规格:

在原生依赖项已缓存后应用更改

环境变量会在解析原生依赖项时读取。如果您在现有项目中更改该变量或 Podfile 子规格,请清除相关原生依赖项状态,并在已导出该变量的 shell 中重新解析。
重新安装 CocoaPods 后,请验证 Podfile.lock 中未出现 OneSignalCompleteOneSignalLocation
无匹配行表示已排除位置模块。富通知、确认送达和 Live Activities 仍可通过上述模块化子规格正常工作。
使用 Xcode 或 Android Studio 时,请从已导出 ONESIGNAL_DISABLE_LOCATION 的终端启动 IDE。在 CI 上,请根据 ONESIGNAL_DISABLE_LOCATION 的值为 DerivedData、Swift Package Manager、CocoaPods 和 Gradle 缓存设置键。

2. 初始化 SDK

根据您项目的框架 Cordova 和/或 Ionic 或 Ionic 和 Capacitor,按照提供的说明初始化 OneSignal。
  • Angular:在您的 src/app/app.component.ts 文件中使用提供的方法初始化 OneSignal。
  • React:在您的 src/App.tsxsrc/index.tsx 文件中使用提供的方法初始化 OneSignal。
  • Vue:在您的 src/main.ts 文件中使用提供的方法初始化 OneSignal。
YOUR_APP_ID 替换为您在 OneSignal 仪表板 设置 > 密钥和 ID 中找到的 OneSignal 应用 ID。
如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。
打开您的 capacitor.config.jsoncapacitor.config.ts 并添加以下代码以允许 OneSignal 处理 iOS 推送通知。
如果订阅失败并出现”APNS Delegate Never Fired”错误,此配置将解决该问题。
在您的 src/app/app.component.ts 文件中使用提供的方法初始化 OneSignal。YOUR_APP_ID 替换为您在 OneSignal 仪表板 设置 > 密钥和 ID 中找到的 OneSignal 应用 ID。
如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。
在您的 www/js/index.js 文件中使用提供的方法初始化 OneSignal。YOUR_APP_ID 替换为您在 OneSignal 仪表板 设置 > 密钥和 ID 中找到的 OneSignal 应用 ID。
如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。

Android 设置

确保您的 OneSignal 应用已使用您的 Firebase 凭据 为 Android 平台进行配置。 设置您的通知图标以匹配您的应用品牌。如果跳过此步骤,推送通知将显示默认的铃铛图标。 为 Android 构建 此时,您应该能够在物理 Android 设备或模拟器上无问题地构建和运行您的应用。
确认您的 Android 构建正常工作后:

iOS 设置

确保您的 OneSignal 应用已使用 p8 令牌(推荐)p12 证书 为 iOS 平台进行配置。 按照以下步骤向您的 iOS 应用添加推送通知,包括对徽章确认送达 和图像的支持。

1. 向应用目标添加推送通知功能

推送通知功能 允许您的应用注册推送令牌并接收通知。
  1. 在 Xcode 中打开您的应用的 .xcworkspace 文件。
  2. 选择 您的应用目标 > 签名和功能
  3. 点击 + 功能 并添加 推送通知 功能

为应用目标添加推送通知功能。

2. 向应用目标添加后台模式功能

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

为应用目标添加远程通知后台执行模式。

3. 将应用目标添加到应用组

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

应用目标是应用组的一部分。

您的应用组名称必须与所有目标中的包 ID 拼写和大小写完全匹配。

4. 添加通知服务扩展

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

选择通知服务扩展目标。

为通知服务扩展命名。

取消激活以继续调试您的应用目标。

将 OneSignalNotificationServiceExtension 的 最低部署目标 设置为与主应用匹配(推荐 iOS 15+)。
如果您使用的是 CocoaPods,请同时在您的 Podfile 中设置部署版本。

设置与主应用相同的部署目标。

5. 将 NSE 目标添加到应用组

使用您在第 3 步中添加的相同应用组 ID。
  1. 转到 OneSignalNotificationServiceExtension > Signing & Capabilities
  2. 添加 App Groups
  3. 添加完全相同的组 ID

NSE 现在与您的应用目标属于同一个应用组。

6. 更新 NSE 代码

  1. 导航到 OneSignalNotificationServiceExtension 文件夹
  2. NotificationService.swiftNotificationService.m 文件的内容替换为以下内容:

导航到您的 NotificationService 文件。

您应该会看到错误,因为 OneSignal 包尚未安装。这将在下一步中解决。

在下一步中安装包之前,此文件会显示错误。

7. 将 OneSignal 添加到 NSE 目标

如果您的 SDK 使用 Swift Package Manager (SPM) 管理 iOS 依赖项,可以跳过此步骤。OneSignal 包已解析并可供所有目标使用。
更新您的 ios/Podfile 以包含模块化的 OneSignalXCFramework/OneSignal subspec。不要使用聚合的 pod 'OneSignalXCFramework' 声明。聚合 pod 会解析为 OneSignalComplete,它会传递包含 OneSignalLocation,即使您已排除位置模块,也可能重新引入位置功能。
在终端中打开您的项目并运行:
shell

常见的 pod install 错误

您可能会遇到以下错误,以下是解决方法。
CocoaPods 依赖 xcodeproj Ruby gem 来读取您的 Xcode 项目文件。截至目前,最新的 xcodeproj 版本不识别 Xcode 16 引入的对象版本 70。因此,当 CocoaPods 尝试打开您的 .xcodeproj 文件时,它会因为这个错误而崩溃。
  1. 关闭 Xcode。
  2. 导航到您项目的 ios/<your-app>.xcodeproj/project.pbxproj 文件。
  3. 更改这一行:objectVersion = 70;
  4. 将其替换为:objectVersion = 55;
  5. 保存、关闭,并重新运行 cd ios pod install cd ..

为 iOS 构建

现在您应该能够在真实的 iOS 设备或 iOS 模拟器(iOS 16.2+)上构建和运行您的应用。

常见的 iOS 构建错误

在使用 Xcode 15+ 构建时,您可能会看到这个错误,这是由于影响跨平台系统的默认配置更改所致。
  1. 在 Xcode 中打开您的 .xcworkspace 文件夹并导航到 您的应用目标 > Build Phases
  2. 您应该有一个名为 “Embed Foundation Extensions”“Embed App Extensions” 的阶段。
  3. 拖放并将此构建阶段移动到 “Run Script” 之上。
  4. 构建和运行您的应用。错误应该得到解决。

Xcode 中 Build Phases 的正确顺序。

取消选中'仅在安装时复制'。

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

PBXGroup 的路径错误。


将文件夹转换为组。

在确认您的 iOS 构建正常工作后,请继续进行 测试 OneSignal SDK 集成

测试 OneSignal SDK 集成

本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。

检查移动端订阅

1

在测试设备上启动您的应用。

如果您在初始化时添加了 requestPermission 方法,原生推送权限提示应该会自动出现。

iOS 和 Android 推送权限提示

2

检查您的 OneSignal 控制台

在接受提示之前,请检查 OneSignal 控制台:
  • 转到 受众 > 订阅
  • 您应该看到一个状态为”从未订阅”的新条目。

控制台显示 '从未订阅' 状态的订阅

3

返回应用并在提示中点击允许。

4

刷新 OneSignal 控制台的订阅页面。

订阅状态现在应该显示为已订阅

控制台显示 '已订阅' 状态的订阅

您已成功创建了移动端订阅。 移动端订阅是在用户首次在设备上打开您的应用时创建的,或者在同一设备上卸载并重新安装您的应用时创建的。

设置测试订阅

测试订阅有助于在发送消息之前测试推送通知。
1

添加到测试订阅。

在控制台中,在订阅旁边,点击选项(三个点)按钮并选择添加到测试订阅

将设备添加到测试订阅

2

为您的订阅命名。

为订阅命名,以便您稍后能够在测试订阅标签中轻松识别您的设备。
3

创建测试用户分组。

转到 受众 > 分组 > 新建分组
4

为分组命名。

将分组命名为 Test Users(名称很重要,因为稍后会使用到)。
5

添加测试用户过滤器并点击创建分组。

使用测试用户过滤器创建 'Test Users' 分组

您已成功创建了测试用户分组。 现在我们可以测试向这个单独的设备和测试用户组发送消息。

通过 API 发送测试推送

1

获取您的应用 API 密钥和应用 ID。

在您的 OneSignal 控制台中,转到 设置 > 密钥和 ID
2

更新提供的代码。

将下面代码中的 YOUR_APP_API_KEYYOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 分组。
3

运行代码。

在您的终端中运行代码。
4

检查图片和确认送达。

如果所有设置步骤都成功完成,测试订阅应该会收到包含图片的通知:

iOS 和 Android 上包含图片的推送通知

图片在折叠的通知视图中会显得很小。展开通知以查看完整图片。
5

检查确认送达。

在您的控制台中,转到 送达 > 已发送消息,然后点击消息查看统计数据。您应该会看到已确认统计,表示设备收到了推送。
您已成功通过我们的 API 向分组发送了通知。
  • 没有收到图片?您的通知服务扩展可能缺失。
  • 没有确认送达?请检查您的应用组设置
  • 遇到问题?将 API 请求和应用启动从开始到结束的日志复制粘贴到 .txt 文件中。然后将两者都发送给 support@onesignal.com

发送应用内消息

应用内消息让您可以在用户使用您的应用时与他们进行沟通。
1

在设备上关闭或将您的应用切换到后台。

这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中,当用户在应用处于后台或关闭至少 30 秒后重新打开应用时,会开始一个新会话。更多详情,请参阅我们的应用内消息如何显示指南。
2

创建应用内消息。

  • 在您的 OneSignal 控制台中,导航到 消息 > 应用内 > 新建应用内消息
  • 找到并选择欢迎消息。
  • 将您的受众设置为我们之前使用的 Test Users 分组。

使用应用内消息定位 'Test Users' 分组

3

如需要,请自定义消息内容。

应用内欢迎消息的自定义示例

4

将触发器设置为 '应用打开时'。

5

安排频率。

安排 > 您希望多久显示一次此消息? 下选择 每次触发条件满足时

应用内消息安排选项

6

使消息生效。

点击 使消息生效,这样每次测试用户打开应用时都可以使用该消息。
7

打开应用并查看消息。

应用内消息生效后,打开您的应用。您应该会看到它显示:

在设备上显示的欢迎应用内消息

没有看到消息?
  • 开始新会话
    • 您必须关闭或将应用切换到后台至少 30 秒后再重新打开。这可以确保开始新会话。
    • 更多信息,请参阅应用内消息如何显示
  • 仍在 Test Users 分组中?
    • 如果您重新安装或更换了设备,请重新将设备添加到测试订阅并确认它是 Test Users 分组的一部分。
  • 遇到问题?
    • 在重现上述步骤时,请遵循获取调试日志。这将生成额外的日志,您可以与 support@onesignal.com 分享,我们将帮助调查正在发生的情况。
您已成功设置 OneSignal SDK 并学习了重要概念,如:继续阅读本指南以在您的应用中识别用户并设置其他功能。

用户识别

之前,我们演示了如何创建移动端订阅。现在我们将扩展到使用 OneSignal SDK 在所有订阅(包括推送、电子邮件和短信)中识别用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件跟踪,以帮助您统一用户并跨平台与他们互动。

分配外部 ID

使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码之间一致地识别用户。这确保您的消息传递在各个渠道和第三方系统中保持统一(对集成特别重要)。 每次您的应用识别用户时,使用我们 SDK 的login 方法设置外部 ID。
OneSignal 为订阅(订阅 ID)和用户(OneSignal ID)生成唯一的只读 ID。当用户在不同设备上下载您的应用、订阅您的网站,和/或在您的应用之外提供电子邮件地址和电话号码时,将创建新的订阅。强烈建议通过我们的 SDK 设置外部 ID,以在用户的所有订阅中识别用户,无论订阅是如何创建的。

添加数据标签

标签是字符串数据的键值对,您可以使用它们来存储用户属性(如 usernamerole 或偏好)和事件(如 purchase_dategame_level 或用户交互)。标签支持高级消息个性化分组,允许更高级的用例。 在您的应用中发生事件时,使用我们 SDK 的addTagaddTags 方法设置标签。 在这个示例中,用户达到了第 6 级,可以通过名为 current_level 的标签识别,其值设置为 6

OneSignal 中带有名为'current_level'标签设置为'6'的用户档案

我们可以创建一个等级在 5 到 10 之间的用户分组,并使用它来发送有针对性的个性化消息:

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


屏幕截图显示针对 5-10 级分组发送的个性化推送通知


iOS 和 Android 设备上收到的包含个性化内容的推送通知

添加电子邮件和/或短信订阅

之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。 如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在,SDK 会将其添加到现有用户,不会创建重复项。 您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。

通过外部 ID 统一的包含推送、电子邮件和短信订阅的用户档案

多渠道沟通的最佳实践
  • 在添加电子邮件或短信订阅之前获得明确同意。
  • 向用户解释每个沟通渠道的好处。
  • 提供渠道偏好,让用户可以选择他们偏好的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管控方法: 有关更多信息,请参阅我们的隐私和安全文档:

提示推送权限

不要在应用打开时立即调用 requestPermission(),而是采取更策略性的方法。在请求权限之前,使用应用内消息解释推送通知的价值。 有关最佳实践和实现细节,请参阅我们的提示推送权限指南。

监听推送、用户和应用内事件

使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南

推送通知事件

要进行完全自定义,请参阅移动端服务扩展

用户状态变化

应用内消息事件


高级设置和功能

探索更多功能以增强您的集成:

移动端 SDK 设置和参考

通过查看移动端推送设置指南,确保您已启用所有关键功能。 有关可用方法和配置选项的完整详细信息,请访问移动端 SDK 参考
恭喜!您已成功完成移动端 SDK 设置指南。

需要帮助?与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息:
  • 您遇到的问题详情以及复现步骤(如有)
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID(如适用)
  • 您在 OneSignal 控制台中测试的消息 URL(如适用)
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助!