概览
本指南说明如何将 OneSignal 推送通知集成到 Flutter 应用程序中。它涵盖了从安装到配置和服务工作者管理的所有内容。要求
- Flutter 3.29.0+
- 配置好的 OneSignal 应用和平台
- 带有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
- 带有 iOS 12+、iPadOS 12+ 的设备,或运行 iOS 16.2+ 的 Xcode 模拟器
- Swift Package Manager(需要手动启用)或 CocoaPods 1.16.2+
- 安装了 Google Play 商店(服务)的 Android 7.0+ 设备或模拟器
配置您的 OneSignal 应用和平台
使用您支持的平台配置您的 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。分步设置说明
分步设置说明
1
创建或选择您的应用
点击 新应用/网站 创建新应用,或在 设置 > 推送和应用内 中向现有应用添加平台。选择您要配置的平台,然后点击 下一步:配置您的平台。

2
配置平台凭据
为您的平台输入凭据:
- Android:设置 Firebase 凭据
- iOS:p8 令牌(推荐) 或 p12 证书
- Amazon:生成 API 密钥
- 华为:授权 OneSignal
3
保存您的应用 ID 并安装 SDK
您的 应用 ID 显示在最终屏幕上。复制并保存它——初始化 SDK 时需要使用它。选择您的 SDK 平台,然后按照设置指南操作。

SDK 设置
1. 添加 SDK
将onesignal_flutter 包添加到您的 pubspec.yaml 文件的 dependencies 下:
pubspec.yaml
flutter pub get 来安装 SDK。
Swift Package Manager (SPM): 从 5.5.0 版本开始,OneSignal Flutter SDK 支持 iOS 的 SPM。SPM 默认未启用——您需要运行
flutter config --enable-swift-package-manager 手动启用。启用后,Flutter 会自动处理 SPM 集成。如果您的项目之前使用 CocoaPods 并希望迁移到 SPM:- 运行
flutter config --enable-swift-package-manager - 删除
Podfile、Podfile.lock和Pods/目录 - 从
ios/Flutter/Debug.xcconfig和ios/Flutter/Release.xcconfig中移除 CocoaPods 引用行 - 运行
flutter run
可选:禁用位置模块
从onesignal_flutter 5.6.0 开始,如果您的应用不使用 OneSignal.Location,您可以从 iOS 和 Android 构建中排除 OneSignal 的原生位置模块。
在为 Swift Package Manager (SPM)、CocoaPods 和 Android Gradle 构建解析或构建依赖项之前,设置 ONESIGNAL_DISABLE_LOCATION=true。该值不区分大小写。您也可以将其设置为 1。
在 GitHub Actions 中,您可以在 job 或 step 级别设置一次该变量,以便 SPM、CocoaPods 和 Gradle 构建继承它:
OneSignal.Location 的调用会被忽略。OneSignal.Location.isShared() 返回 false。
在扩展目标中使用模块化 CocoaPods 子规格
如果您的 iOSPodfile 在通知服务扩展或其他扩展目标中显式添加了 OneSignalXCFramework,请使用模块化子规格。聚合声明 pod 'OneSignalXCFramework' 会解析为 OneSignalComplete,其中包含 OneSignalLocation,从而使 ONESIGNAL_DISABLE_LOCATION 失效。
在包已缓存后应用更改
该环境变量仅在解析依赖项时读取,并且每个平台都会缓存已解析的集合。如果您在现有项目中更改该变量或 Podfile 子规格,请清除相关缓存,并在已导出该变量的 shell 中重新解析依赖项。否则,过期构建可能会保留或移除位置模块,而不受新值影响。 对于 CocoaPods 项目:Podfile.lock 中未出现 OneSignalComplete 或 OneSignalLocation:
2. 初始化 SDK
在您的main.dart 文件中,使用提供的方法在您的应用根组件中初始化 OneSignal。
将 YOUR_APP_ID 替换为在您的 OneSignal 仪表板 设置 > 密钥和 ID 中找到的 OneSignal 应用 ID。
如果您无权访问 OneSignal 应用,请要求您的团队成员邀请您。
main.dart
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 目标
如果您的 SDK 使用 Swift Package Manager (SPM) 管理 iOS 依赖项,可以跳过此步骤。OneSignal 包已解析并可供所有目标使用。
ios/Podfile 以包含模块化的 OneSignalXCFramework/OneSignal subspec。不要使用聚合的 pod 'OneSignalXCFramework' 声明。聚合 pod 会解析为 OneSignalComplete,它会传递包含 OneSignalLocation,即使您已排除位置模块,也可能重新引入位置功能。
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 集成是否正常工作。检查移动端订阅
1
在测试设备上启动您的应用。
如果您在初始化时添加了 
requestPermission 方法,原生推送权限提示应该会自动出现。
2
检查您的 OneSignal 控制台
在接受提示之前,请检查 OneSignal 控制台:
- 转到 受众 > 订阅。
- 您应该看到一个状态为”从未订阅”的新条目。

3
返回应用并在提示中点击允许。
4
刷新 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
检查图片和确认送达。
如果所有设置步骤都成功完成,测试订阅应该会收到包含图片的通知:

图片在折叠的通知视图中会显得很小。展开通知以查看完整图片。
5
检查确认送达。
在您的控制台中,转到 送达 > 已发送消息,然后点击消息查看统计数据。您应该会看到已确认统计,表示设备收到了推送。
您已成功通过我们的 API 向分组发送了通知。
发送应用内消息
应用内消息让您可以在用户使用您的应用时与他们进行沟通。1
在设备上关闭或将您的应用切换到后台。
这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中,当用户在应用处于后台或关闭至少 30 秒后重新打开应用时,会开始一个新会话。更多详情,请参阅我们的应用内消息如何显示指南。
2
创建应用内消息。
- 在您的 OneSignal 控制台中,导航到 消息 > 应用内 > 新建应用内消息。
- 找到并选择欢迎消息。
- 将您的受众设置为我们之前使用的 Test Users 分组。

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

4
将触发器设置为 '应用打开时'。
5
安排频率。
在 安排 > 您希望多久显示一次此消息? 下选择 每次触发条件满足时。

6
使消息生效。
点击 使消息生效,这样每次测试用户打开应用时都可以使用该消息。
7
打开应用并查看消息。
应用内消息生效后,打开您的应用。您应该会看到它显示:

用户识别
之前,我们演示了如何创建移动端订阅。现在我们将扩展到使用 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(如适用)
- 任何相关的日志或错误信息

