跳转到主要内容
本指南适用于 Flutterflow 移动应用程序设置。如果您有 Flutterflow 网站,请查看我们的 Web SDK 设置 指南。

要求

  • Flutterflow 计划:标准版或更高版本
  • 已配置的 OneSignal 应用程序和平台
iOS 要求
  • 带有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
  • iOS 12+、iPadOS 12+ 或运行 iOS 16.2+ 的 Xcode 模拟器设备
  • CocoaPods 1.16.2+
Android 要求
  • Android 7.0+ 设备或安装了 Google Play Store(Services)的模拟器

配置您的 OneSignal 应用和平台

推送通知所需设置 要开始使用 OneSignal 发送推送通知,您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。
如果您的组织已有 OneSignal 账户,请要求邀请您为管理员角色以配置应用。否则,请注册免费账户以开始使用。
您可以在单个 OneSignal 应用下管理多个平台(iOS、Android、华为、Amazon、Web)。
1

创建或选择您的应用

  • 要向现有应用添加平台,请在 OneSignal 控制台中转到 设置 > 推送和应用内
  • 要重新开始,请点击 新应用/网站 并按照提示操作。

示例显示创建新应用。

2

设置并激活平台

  • 为您的应用和组织选择一个清晰且易识别的名称。
  • 选择您要配置的平台(iOS、Android 等)。
  • 点击 下一步:配置您的平台

设置首个 OneSignal 应用、组织和频道的示例。

3

配置平台凭据

根据您的平台按照提示操作:输入您的凭据后点击 保存并继续
4

选择目标 SDK

选择与您的开发平台匹配的 SDK(例如,iOS、Android、React Native、Unity),然后点击 保存并继续

选择您正在使用的 SDK 以导航到文档。

5

安装 SDK 并保存您的应用 ID

配置好您的平台后,将显示您的 OneSignal 应用 ID。复制并保存此 ID——在安装和初始化 SDK 时您将需要它。如果与他人协作,请使用 邀请 按钮添加开发人员或团队成员,然后点击 完成 以完成设置。

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

完成后,请遵循您所选平台的 SDK 安装指南以完成 OneSignal 集成。

设置

1. 创建新的自定义操作

在您的 Flutterflow 项目中,导航到自定义代码,然后单击 +Add 按钮并选择操作。
在右侧工具栏的操作设置下,单击添加依赖项并输入以下依赖项,然后单击刷新将其添加到操作中:
dependency
  dependencies:
  	onesignal_flutter: ^5.1.2
在操作代码中,在预加载的代码下添加以下内容,然后保存并编译您的操作。 YOUR_APP_ID 替换为在您的 OneSignal 仪表板 设置 > Keys & IDs 中找到的 OneSignal 应用程序 ID。
如果您无权访问 OneSignal 应用程序,请要求您的团队成员邀请您。
Flutter
  import 'package:onesignal_flutter/onesignal_flutter.dart';

  Future onesignal() async {
    //Remove this method to stop OneSignal Debugging
    OneSignal.Debug.setLogLevel(OSLogLevel.verbose);

    OneSignal.initialize("YOUR_APP_ID");

    // The promptForPushNotificationsWithUserResponse function will show the iOS or Android push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission
    OneSignal.Notifications.requestPermission(true);
  }
接下来,单击左侧工具栏中的 main.dart 文件,然后单击右侧栏中初始操作旁边的 + 图标,并单击刚刚创建的 onesignal 操作。
这将把操作添加到您的应用程序中,并在应用程序运行时初始化 OneSignal SDK:

2. 导出项目

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

3. iOS 设置

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

添加通知服务扩展

OneSignalNotificationServiceExtension 允许您的 iOS 应用程序接收包含图像、按钮和徽章的丰富通知。OneSignal 的确认交付分析功能也需要它。 在 Xcode 中选择 文件 > 新建 > 目标… 选择通知服务扩展,然后单击下一步
输入产品名称为 OneSignalNotificationServiceExtension 并按完成
不要在选择完成后显示的对话框中激活方案。 在“激活方案”提示上按取消

通过取消,您可以继续调试您的应用程序,而不是刚创建的扩展。如果您意外激活了,您可以在设备选择器附近的中上部切换回调试您的应用程序目标。

选择 OneSignalNotificationServiceExtension 目标和通用设置。 最低部署版本设置为与您的主应用程序目标相同的值。这应该是 iOS 11 或更高版本。

这应该与您的主应用程序目标的值相同。

添加 App Groups

App Groups 允许您的应用程序和 OneSignalNotificationServiceExtension 在收到通知时进行通信,即使您的应用程序未处于活动状态。这对于徽章和确认交付是必需的。 选择您的主应用程序目标 > 签名和功能 > + Capability > App Groups
App Groups 中,单击 + 按钮。 将 App Groups 容器设置为 group.YOUR_BUNDLE_IDENTIFIER.onesignal,其中 YOUR_BUNDLE_IDENTIFIER 与您的主应用程序“Bundle Identifier”相同。
OK 并对 OneSignalNotificationServiceExtension 目标重复。 选择 OneSignalNotificationServiceExtension 目标 > 签名和功能 > + Capability > App Groups
App Groups 中,单击 + 按钮。 将 App Groups 容器设置为 group.YOUR_BUNDLE_IDENTIFIER.onesignal,其中 YOUR_BUNDLE_IDENTIFIER 与**您的主应用程序“Bundle Identifier”**相同。 不要包含 OneSignalNotificationServiceExtension

不要包含 OneSignalNotificationServiceExtension

只有在您想使用默认应用组名称(即 group.{your_bundle_id}.onesignal)时才需要此步骤。打开您的 Info.plist 文件并添加一个新的 OneSignal_app_groups_key 作为 String 类型。输入您在上一步中检查的组名称作为其值。确保在 OneSignalNotificationServiceExtension 文件夹下的 Info.plist 中也做同样的操作。

将 OneSignal SDK 添加到 OneSignalNotificationServiceExtension

更新您的 ios/Podfile 以包含:
target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
end
在您的 Podfile 顶部确保您有 platform :ios, '11.0'。- 或者如果您的应用程序需要,则使用更新的 iOS 版本。
# Uncomment this line to define a global platform for your project
platform :ios, '11.0'
打开终端,cdios 目录,然后运行 pod install 如果您看到下面的错误,请在您的 podfile 顶部添加 use_frameworks! 并再试一次。
- Runner (true) and OneSignalNotificationServiceExtension (false) do not both set use_frameworks!.

OneSignalNotificationServiceExtension 代码

在 Xcode 项目导航器中,选择 OneSignalNotificationServiceExtension 文件夹并打开 NotificationService.mNotificationService.swift 文件。 用以下代码替换整个文件的内容。
import UserNotifications

import OneSignalExtension

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            /* DEBUGGING: Uncomment the 2 lines below to check this extension is executing
                          Note, this extension only runs when mutable-content is set
                          Setting an attachment or action buttons automatically adds this */
            // print("Running NotificationServiceExtension")
            // bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

            OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
}

NotificationService.swift 文件的示例。


测试 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 分组。
curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
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 设置指南。


I