要求
- Flutterflow 计划:标准版或更高版本
- 已配置的 OneSignal 应用程序和平台
- 带有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
- iOS 12+、iPadOS 12+ 或运行 iOS 16.2+ 的 Xcode 模拟器设备
- CocoaPods 1.16.2+
- Android 7.0+ 设备或安装了 Google Play Store(Services)的模拟器
配置您的 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
设置
1. 创建新的自定义操作
在您的 Flutterflow 项目中,导航到自定义代码,然后单击 +Add 按钮并选择操作。
dependency

YOUR_APP_ID 替换为在您的 OneSignal 仪表板 设置 > Keys & IDs 中找到的 OneSignal 应用程序 ID。
如果您无权访问 OneSignal 应用程序,请要求您的团队成员邀请您。
Flutter
onesignal 操作。


2. 导出项目
- APK 下载(仅 Android)
- 完整项目下载(iOS 和 Android)
打开开发者菜单并下载 APK:
APK 下载完成后,您可以通过将 APK 拖入 Android 模拟器来安装并测试应用程序。推送功能应该立即工作,您可以在通过原生提示提供推送权限后立即向设备发送推送通知。

3. iOS 设置
下载的项目可能不会立即可以在 iOS 中启动。在设置 OneSignal 特定附加功能之前,您需要确保项目已完全构建。操作如下:- 打开终端窗口,cd(更改目录)到下载项目的
ios文件夹。 - 在终端中输入
flutter build ios并按 Enter 键。等待构建完成,这可能需要一些时间,具体取决于您项目的大小。 - 仍在终端中输入
pod install并按 Enter 键。等待 pod 安装完成。
.xcworkspace 文件。
选择根项目 > 您的主应用程序目标 > 签名和功能。
如果您没有看到推送通知已启用,请单击 + Capability 并添加推送通知。确保为您的团队和 Bundle Identifier 输入正确的详细信息。


添加通知服务扩展
OneSignalNotificationServiceExtension 允许您的 iOS 应用程序接收包含图像、按钮和徽章的丰富通知。OneSignal 的确认交付分析功能也需要它。 在 Xcode 中选择 文件 > 新建 > 目标… 选择通知服务扩展,然后单击下一步。
OneSignalNotificationServiceExtension 并按完成。



添加 App Groups
App Groups 允许您的应用程序和 OneSignalNotificationServiceExtension 在收到通知时进行通信,即使您的应用程序未处于活动状态。这对于徽章和确认交付是必需的。 选择您的主应用程序目标 > 签名和功能 > + Capability > App Groups。
group.YOUR_BUNDLE_IDENTIFIER.onesignal,其中 YOUR_BUNDLE_IDENTIFIER 与您的主应用程序“Bundle Identifier”相同。


group.YOUR_BUNDLE_IDENTIFIER.onesignal,其中 YOUR_BUNDLE_IDENTIFIER 与**您的主应用程序“Bundle Identifier”**相同。
不要包含 OneSignalNotificationServiceExtension。

Optional instructions to setup custom App Group Name
Optional instructions to setup custom App Group Name
只有在您不想使用默认应用组名称(即
group.{your_bundle_id}.onesignal)时才需要此步骤。打开您的 Info.plist 文件并添加一个新的 OneSignal_app_groups_key 作为 String 类型。输入您在上一步中检查的组名称作为其值。确保在 OneSignalNotificationServiceExtension 文件夹下的 Info.plist 中也做同样的操作。将 OneSignal SDK 添加到 OneSignalNotificationServiceExtension
更新您的ios/Podfile 以包含:
Podfile 顶部确保您有 platform :ios, '11.0'。- 或者如果您的应用程序需要,则使用更新的 iOS 版本。
cd 到 ios 目录,然后运行 pod install。
如果您看到下面的错误,请在您的 podfile 顶部添加 use_frameworks! 并再试一次。
OneSignalNotificationServiceExtension 代码
在 Xcode 项目导航器中,选择 OneSignalNotificationServiceExtension 文件夹并打开NotificationService.m 或 NotificationService.swift 文件。
用以下代码替换整个文件的内容。

测试 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 设置指南。
















