iOS 推送通知对于在您的 iOS 应用中推动持续的用户参与度和留存率至关重要。它们使您能够直接向用户提供实时更新、提醒和个性化消息,从而改善整体用户体验和应用的粘性。通过将 OneSignal 的 SDK 与您的应用集成,您可以利用 Apple 推送通知服务 (APNS) 确保您的通知在 iOS 设备上无缝传递。本指南将指导您将我们的 SDK 集成到您的 iOS 应用中。
- 带有 Xcode 14+ 的 macOS(设置说明使用 Xcode 16.2)
- 带有 iOS 12+、iPadOS 12+ 的设备,或运行 iOS 16.2+ 的 Xcode 模拟器
- 配置好的 OneSignal 应用和平台
配置您的 OneSignal 应用和平台
使用您支持的平台配置您的 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。
创建或选择您的应用
点击 新应用/网站 创建新应用,或在 设置 > 推送和应用内 中向现有应用添加平台。选择您要配置的平台,然后点击 下一步:配置您的平台。 配置平台凭据
为您的平台输入凭据:输入您的凭据后点击 保存并继续。 保存您的应用 ID 并安装 SDK
您的 应用 ID 显示在最终屏幕上。复制并保存它——初始化 SDK 时需要使用它。选择您的 SDK 平台,然后按照设置指南操作。
iOS 设置
按照以下步骤向您的 iOS 应用添加推送通知,包括支持徽章、确认送达和图像。
1. 向应用目标添加推送通知功能
推送通知功能允许您的应用注册推送令牌并接收通知。
- 在 Xcode 中打开您应用的
.xcworkspace 文件。
- 选择您的应用目标 > 签名和功能
- 点击 + 功能并添加推送通知功能
2. 向应用目标添加后台模式功能
这使您的应用能够在推送通知到达时在后台唤醒。
- 添加后台模式功能
- 启用远程通知
3. 将应用目标添加到应用组
应用组允许在您的应用和通知服务扩展之间共享数据。确认送达和徽章功能所必需。
- 添加应用组功能
- 在应用组功能中点击 +
- 按以下格式添加新的容器 ID:
group.your_bundle_id.onesignal
- 保持 group. 和 .onesignal 前缀和后缀。用您应用的包标识符替换
your_bundle_id。
- 例如,包标识符
com.onesignal.MyApp 将具有容器名称 group.com.onesignal.MyApp.onesignal。
您的应用组名称必须完全匹配您在所有目标中的包 ID 拼写和大小写。
- 打开您应用的
Info.plist
- 添加新属性:
- 键:
OneSignal_app_groups_key
- 值: 您现有的应用组名称(例如,
group.com.example.mycustomgroup)
<key>OneSignal_app_groups_key</key>
<string>group.com.example.mycustomgroup</string>
4. 添加通知服务扩展
Notification Service Extension (NSE) 允许丰富的通知和确认送达分析。
- 在 Xcode 中:File > New > Target…
- 选择 Notification Service Extension,然后 Next。
- 将产品名称设置为
OneSignalNotificationServiceExtension 并按 Finish。
- 在 Activate scheme 提示上按 Don’t Activate。
将 OneSignalNotificationServiceExtension 的 Minimum Deployment Target 设置为与您的主应用匹配(建议 iOS 15+)。
如果您使用 CocoaPods,请也在您的 Podfile 中设置部署版本。
5. 将 NSE 目标添加到应用组
使用您在步骤 3 中添加的相同应用组 ID。
- 转到 OneSignalNotificationServiceExtension > Signing & Capabilities
- 添加 App Groups
- 添加完全相同的组 ID
6. 更新 NSE 代码
- 导航到 OneSignalNotificationServiceExtension 文件夹
- 使用以下内容替换
NotificationService.swift 或 NotificationService.m 文件的内容:
import UserNotifications
import OneSignalExtension
class NotificationService: UNNotificationServiceExtension {
var contentHandler: ((UNNotificationContent) -> Void)?
var receivedRequest: UNNotificationRequest!
var bestAttemptContent: UNMutableNotificationContent?
// 注意,此扩展仅在设置 `mutable_content` 时运行
// 设置附件或操作按钮会自动将属性设置为 true
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
// print("Running NotificationServiceExtension")
// bestAttemptContent.body = "[Modified] " + bestAttemptContent.body
OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
}
}
override func serviceExtensionTimeWillExpire() {
// 将此作为交付修改内容的“最佳尝试”的机会,否则将使用原始推送载荷。
if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
contentHandler(bestAttemptContent)
}
}
}
您应该会看到一个错误,因为 OneSignal 包尚未安装。这将在下一步中解决。
SDK设置
本部分将指导您集成 OneSignal 的核心功能。在本部分结束时,您将拥有与我们 SDK 的基本集成,使您能够触发应用内消息并接收推送通知。
1. 添加 SDK
使用 Xcode Package Dependencies Manager (Swift Package Manager) 或 CocoaPods 添加我们的 SDK。有 4 个可用的库。如果您不需要应用内消息和/或位置追踪,您可以省略这些包。
| 库 | 目标 | 必需 |
|---|
| OneSignalExtension | OneSignalNotificationServiceExtension | ✅ |
| OneSignalFramework | App | ✅ |
| OneSignalInAppMessages | App | 推荐 |
| OneSignalLocation | App | 可选 |
导航到 File > Add Package Dependencies… 并输入 OneSignal SDK 仓库的 URL:https://github.com/OneSignal/OneSignal-XCFramework选择 onesignal-xcframework 包并点击 Add Package。为 OneSignal-XCFramework 选择包产品。
- 重要:将 OneSignalExtension 添加到 OneSignalNotificationServiceExtension Target。
- 将 OneSignalFramework 添加到您的 App Target。
- 如果您计划使用应用内消息(推荐)和/或位置追踪,那么也请将这些包添加到您的 App Target。
有关更多详情,请参阅 Apple 的添加包依赖文档。 要求:CocoaPods 1.16.2+(设置说明使用 CocoaPods 1.16.2)。打开您的 Podfile 并添加以下内容: # 如果 platform 未注释,请设置为与您在 Xcode 中的最小部署目标相同的值
# platform :ios, '15.0'
target 'your_project_name' do
pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
# 如果您的应用不使用应用内消息,您可以移除此项:
pod 'OneSignal/OneSignalInAppMessages', '>= 5.2.9', '< 6.0'
# 如果您的应用不使用 CoreLocation,您可以移除此项:
pod 'OneSignal/OneSignalLocation', '>= 5.2.9', '< 6.0'
# 您的其他 pods 在此
end
target 'OneSignalNotificationServiceExtension' do
pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
end
将依赖添加到您的主应用目标和 OneSignalNotificationServiceExtension 目标。如果 platform 未注释,请确保它与 Xcode 中的最小部署目标值相同。运行以下命令以下载 OneSignal iOS SDK pod 并将其添加到您的项目:pod repo update && pod install安装完成后,请确保打开以您的项目命名的 XCWorkspace 文件(例如,<project-name>.xcworkspace)使用 OneSignal iOS SDK pod 时,您必须专门使用 .xcworkspace 文件来打开项目。
您可能遇到以下错误,以下是解决方法。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 ..
2. 初始化 SDK
根据您的 Xcode 界面设置,按照以下选项初始化 OneSignal。
如果使用 SwiftUI 界面,请导航到您的 <APP_NAME>App.swift 文件并使用提供的方法初始化 OneSignal。将 YOUR_APP_ID 替换为您在 OneSignal 仪表板 Settings > Keys & IDs 中找到的 OneSignal App ID。如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。import SwiftUI
import OneSignalFramework
@main
struct YOURAPP_NAME: App {
//将 SwiftUI 应用连接到 UIKit 应用委托
@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
class AppDelegate: NSObject, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
// 启用详细日志记录以便调试(在生产中移除)
OneSignal.Debug.setLogLevel(.LL_VERBOSE)
// 使用您的 OneSignal App ID 初始化
OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
// 使用此方法提示推送通知。
// 我们建议在测试后移除此方法,而改用应用内消息提示通知权限。
OneSignal.Notifications.requestPermission({ accepted in
print("User accepted notifications: \(accepted)")
}, fallbackToSettings: false)
return true
}
}
如果使用 Storyboard 界面,请导航到您的 AppDelegate 文件并使用提供的方法初始化 OneSignal。将 YOUR_APP_ID 替换为您在 OneSignal 仪表板 Settings > Keys & IDs 中找到的 OneSignal App ID。如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。//AppDelegate.swift
import UIKit
import OneSignalFramework
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// 启用详细日志记录以便调试(在生产中移除)
OneSignal.Debug.setLogLevel(.LL_VERBOSE)
// 使用您的 OneSignal App ID 初始化
OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
// 使用此方法提示推送通知。
// 我们建议在测试后移除此方法,而改用应用内消息提示通知权限。
OneSignal.Notifications.requestPermission({ accepted in
print("User accepted notifications: \(accepted)")
}, fallbackToSettings: false)
return true
}
// AppDelegate 类的剩余内容...
}
禁用方法 swizzling(可选)
默认情况下,OneSignal SDK 使用方法 swizzling 自动处理推送通知委托方法。如果您的应用需要禁用 swizzling(例如,为了避免与其他 SDK 冲突或保持对通知委托方法的完全控制),您可以通过 Info.plist 选择退出。
禁用 swizzling 后,您必须手动将通知委托方法转发到 OneSignal SDK。所有其他 SDK 功能(监听器、观察者、应用内消息、结果等)继续正常工作。
步骤 1. 添加 Info.plist 标志
将以下内容添加到您应用的 Info.plist:
<key>OneSignal_disable_swizzling</key>
<true/>
当 SDK 检测到此标志时,它会在启动时跳过所有方法 swizzling,并记录警告提醒您实现手动转发。
步骤 2. 设置 UNUserNotificationCenter 委托
在调用 OneSignal.initialize 之前,将您的 AppDelegate 设置为 UNUserNotificationCenter 委托。否则,前台通知显示和通知点击处理将无法正常工作。
// In application(_:didFinishLaunchingWithOptions:), BEFORE OneSignal.initialize()
UNUserNotificationCenter.current().delegate = self
步骤 3. 转发通知委托方法
在您的 AppDelegate 中实现以下方法。所有方法通过 OneSignal.Notifications 调用。
令牌注册:
func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
OneSignal.Notifications.didRegisterForRemoteNotifications(application, deviceToken: deviceToken)
}
func application(_ application: UIApplication,
didFailToRegisterForRemoteNotificationsWithError error: Error) {
OneSignal.Notifications.handleDidFailRegisterForRemoteNotification(error as NSError)
}
后台/静默通知:
func application(_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable: Any],
fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
OneSignal.Notifications.receiveRemoteNotification(application,
userInfo: userInfo,
completionHandler: completionHandler)
}
前台通知显示:
SDK 会通过 OSNotification 对象调用您的完成块。如果非 nil,SDK 希望显示通知——传递您首选的展示选项。如果为 nil(例如,IAM 预览),则不传递任何展示选项。
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
OneSignal.Notifications.handleWillPresentNotificationInForeground(
withPayload: notification.request.content.userInfo
) { notif in
if notif != nil {
if #available(iOS 14.0, *) {
completionHandler([.banner, .list, .sound])
} else {
completionHandler([.alert, .sound])
}
} else {
completionHandler([])
}
}
}
onWillDisplayNotification 生命周期监听器和 preventDefault / display API 继续支持手动转发。SDK 从 handleWillPresentNotificationInForegroundWithPayload 内部调用您的监听器。
通知点击/操作:
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
OneSignal.Notifications.handleNotificationResponse(response)
completionHandler()
}
可选:设置角标数量
禁用 swizzling 后,SDK 无法拦截角标变化。使用此方法设置角标数量并与 OneSignal 的内部角标缓存保持同步:
OneSignal.Notifications.setBadgeCount(5)
SwiftUI 应用
SwiftUI 应用默认没有 AppDelegate。使用 @UIApplicationDelegateAdaptor 添加一个,然后实现上面所示的所有转发方法:
@main
struct YourApp: App {
@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
UNUserNotificationCenter.current().delegate = self
OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
return true
}
// Implement all the forwarding methods shown above
}
API 参考
| 方法 | 用途 |
|---|
didRegisterForRemoteNotifications(_:deviceToken:) | 将 APNs 设备令牌转发到 OneSignal |
handleDidFailRegisterForRemoteNotification(_:) | 转发 APNs 注册失败 |
receiveRemoteNotification(_:userInfo:completionHandler:) | 转发后台/静默通知 |
handleWillPresentNotificationInForegroundWithPayload(_:withCompletion:) | 转发前台通知供 SDK 处理 |
handleNotificationResponse(_:) | 将通知点击/操作转发到 SDK |
setBadgeCount(_:) | 设置角标数量并与 SDK 缓存同步 |
测试 OneSignal SDK 集成
本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。
检查移动端订阅
在测试设备上启动您的应用。
如果您在初始化时添加了 requestPermission 方法,原生推送权限提示应该会自动出现。 检查您的 OneSignal 控制台
在接受提示之前,请检查 OneSignal 控制台:
- 转到 受众 > 订阅。
- 您应该看到一个状态为”从未订阅”的新条目。
刷新 OneSignal 控制台的订阅页面。
订阅状态现在应该显示为已订阅。您已成功创建了
移动端订阅。
移动端订阅是在用户首次在设备上打开您的应用时创建的,或者在同一设备上卸载并重新安装您的应用时创建的。
设置测试订阅
测试订阅有助于在发送消息之前测试推送通知。
添加到测试订阅。
在控制台中,在订阅旁边,点击选项(三个点)按钮并选择添加到测试订阅。 为您的订阅命名。
为订阅命名,以便您稍后能够在测试订阅标签中轻松识别您的设备。
创建测试用户分组。
转到 受众 > 分组 > 新建分组。
为分组命名。
将分组命名为 Test Users(名称很重要,因为稍后会使用到)。
添加测试用户过滤器并点击创建分组。
您已成功创建了测试用户分组。
现在我们可以测试向这个单独的设备和测试用户组发送消息。
通过 API 发送测试推送
获取您的应用 API 密钥和应用 ID。
在您的 OneSignal 控制台中,转到 设置 > 密钥和 ID。 更新提供的代码。
将下面代码中的 YOUR_APP_API_KEY 和 YOUR_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"
}'
检查图片和确认送达。
如果所有设置步骤都成功完成,测试订阅应该会收到包含图片的通知:图片在折叠的通知视图中会显得很小。展开通知以查看完整图片。
检查确认送达。
在您的控制台中,转到 送达 > 已发送消息,然后点击消息查看统计数据。您应该会看到已确认统计,表示设备收到了推送。
- 没有收到图片?您的通知服务扩展可能缺失。
- 没有确认送达?请检查您的应用组设置。
- 遇到问题?将 API 请求和应用启动从开始到结束的日志复制粘贴到
.txt 文件中。然后将两者都发送给 support@onesignal.com。
发送应用内消息
应用内消息让您可以在用户使用您的应用时与他们进行沟通。
在设备上关闭或将您的应用切换到后台。
这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中,当用户在应用处于后台或关闭至少 30 秒后重新打开应用时,会开始一个新会话。更多详情,请参阅我们的应用内消息如何显示指南。 创建应用内消息。
- 在您的 OneSignal 控制台中,导航到 消息 > 应用内 > 新建应用内消息。
- 找到并选择欢迎消息。
- 将您的受众设置为我们之前使用的 Test Users 分组。
安排频率。
在 安排 > 您希望多久显示一次此消息? 下选择 每次触发条件满足时。 使消息生效。
点击 使消息生效,这样每次测试用户打开应用时都可以使用该消息。
打开应用并查看消息。
应用内消息生效后,打开您的应用。您应该会看到它显示:没有看到消息?
- 开始新会话
- 您必须关闭或将应用切换到后台至少 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,以在用户的所有订阅中识别用户,无论订阅是如何创建的。
添加数据标签
标签是字符串数据的键值对,您可以使用它们来存储用户属性(如 username、role 或偏好)和事件(如 purchase_date、game_level 或用户交互)。标签支持高级消息个性化和分组,允许更高级的用例。
在您的应用中发生事件时,使用我们 SDK 的addTag 和 addTags 方法设置标签。
在这个示例中,用户达到了第 6 级,可以通过名为 current_level 的标签识别,其值设置为 6。
我们可以创建一个等级在 5 到 10 之间的用户分组,并使用它来发送有针对性的个性化消息:
添加电子邮件和/或短信订阅
之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。
如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在,SDK 会将其添加到现有用户,不会创建重复项。
您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。
多渠道沟通的最佳实践
- 在添加电子邮件或短信订阅之前获得明确同意。
- 向用户解释每个沟通渠道的好处。
- 提供渠道偏好,让用户可以选择他们偏好的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管控方法:
有关更多信息,请参阅我们的隐私和安全文档:
提示推送权限
不要在应用打开时立即调用 requestPermission(),而是采取更策略性的方法。在请求权限之前,使用应用内消息解释推送通知的价值。
有关最佳实践和实现细节,请参阅我们的提示推送权限指南。
监听推送、用户和应用内事件
使用 SDK 监听器来响应用户操作和状态变化。
SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。
推送通知事件
要进行完全自定义,请参阅移动端服务扩展。
用户状态变化
应用内消息事件
高级设置和功能
探索更多功能以增强您的集成:
移动端 SDK 设置和参考
通过查看移动端推送设置指南,确保您已启用所有关键功能。
有关可用方法和配置选项的完整详细信息,请访问移动端 SDK 参考。
需要帮助?与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息:
- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息
我们很乐意为您提供帮助!