概述
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 发送推送通知,您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。配置 OneSignal 应用的分步说明。
配置 OneSignal 应用的分步说明。
创建或选择您的应用
- 要向现有应用添加平台,请在 OneSignal 控制台中转到 设置 > 推送和应用内。
- 要重新开始,请点击 新应用/网站 并按照提示操作。

示例显示创建新应用。
设置并激活平台
- 为您的应用和组织选择一个清晰且易识别的名称。
- 选择您要配置的平台(iOS、Android 等)。
- 点击 下一步:配置您的平台。

设置首个 OneSignal 应用、组织和频道的示例。
配置平台凭据
- Android:设置 Firebase 凭据
- iOS:p8 令牌(推荐) 或 p12 证书
- Amazon:生成 API 密钥
- 华为:授权 OneSignal
选择目标 SDK

选择您正在使用的 SDK 以导航到文档。
安装 SDK 并保存您的应用 ID

保存您的应用 ID 并邀请其他团队成员。
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
。

应用目标是应用组的一部分。
4. 添加通知服务扩展
Notification Service Extension (NSE) 允许丰富的通知和确认送达分析。- 在 Xcode 中:File > New > Target…
- 选择 Notification Service Extension,然后 Next。
- 将产品名称设置为
OneSignalNotificationServiceExtension
并按 Finish。 - 在 Activate scheme 提示上按 Don’t Activate。

选择通知服务扩展目标。

命名通知服务扩展。

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

设置与主应用相同的部署目标。
5. 将 NSE 目标添加到应用组
使用您在步骤 3 中添加的相同应用组 ID。- 转到 OneSignalNotificationServiceExtension > Signing & Capabilities
- 添加 App Groups
- 添加完全相同的组 ID

NSE 现在与您的应用目标属于同一个应用组。
6. 更新 NSE 代码
- 导航到 OneSignalNotificationServiceExtension 文件夹
- 使用以下内容替换
NotificationService.swift
或NotificationService.m
文件的内容:

导航到您的 NotificationService 文件。

在您在下一步安装包之前,此文件将显示错误。
SDK设置
本部分将指导您集成 OneSignal 的核心功能。在本部分结束时,您将拥有与我们 SDK 的基本集成,使您能够触发应用内消息并接收推送通知。1. 添加 SDK
使用 Xcode Package Dependencies Manager 或 CocoaPods 添加我们的 SDK。有 4 个可用的库。如果您不需要应用内消息和/或位置追踪,您可以省略这些包。库 | 目标 | 必需 |
---|---|---|
OneSignalExtension | OneSignalNotificationServiceExtension | ✅ |
OneSignalFramework | App | ✅ |
OneSignalInAppMessages | App | 推荐 |
OneSignalLocation | App | 可选 |
- Xcode 包依赖
- CocoaPods
https://github.com/OneSignal/OneSignal-iOS-SDK
选择 onesignal-ios-sdk 包并点击 Add Package。为 OneSignal-iOS-SDK 选择包产品。- 重要:将 OneSignalExtension 添加到 OneSignalNotificationServiceExtension Target。
- 将 OneSignalFramework 添加到您的 App Target。
- 如果您计划使用应用内消息(推荐)和/或位置追踪,那么也请将这些包添加到您的 App Target。

如果您的应用不需要位置追踪,您可以像此示例中显示的那样移除该包。
2. 初始化 SDK
根据您的 Xcode 界面设置,按照以下选项初始化 OneSignal。- SwiftUI
- Storyboard
<APP_NAME>App.swift
文件并使用提供的方法初始化 OneSignal。将 YOUR_APP_ID
替换为您在 OneSignal 仪表板 Settings > Keys & IDs 中找到的 OneSignal App ID。如果您无法访问 OneSignal 应用,请要求您的团队成员邀请您。测试 OneSignal SDK 集成
本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。检查移动端订阅
在测试设备上启动您的应用。
requestPermission
方法,原生推送权限提示应该会自动出现。
iOS 和 Android 推送权限提示
检查您的 OneSignal 控制台
- 转到 受众 > 订阅。
- 您应该看到一个状态为”从未订阅”的新条目。

控制台显示 '从未订阅' 状态的订阅
返回应用并在提示中点击允许。
刷新 OneSignal 控制台的订阅页面。
设置测试订阅
测试订阅有助于在发送消息之前测试推送通知。添加到测试订阅。

将设备添加到测试订阅
为您的订阅命名。

控制台显示 '为您的订阅命名' 字段
创建测试用户分组。
为分组命名。
Test Users
(名称很重要,因为稍后会使用到)。添加测试用户过滤器并点击创建分组。

使用测试用户过滤器创建 'Test Users' 分组
通过 API 发送测试推送
获取您的应用 API 密钥和应用 ID。
更新提供的代码。
YOUR_APP_API_KEY
和 YOUR_APP_ID
替换为您的实际密钥。此代码使用我们之前创建的 Test Users
分组。运行代码。
检查图片和确认送达。

iOS 和 Android 上包含图片的推送通知
发送应用内消息
应用内消息让您可以在用户使用您的应用时与他们进行沟通。在设备上关闭或将您的应用切换到后台。
创建应用内消息。
- 在您的 OneSignal 控制台中,导航到 消息 > 应用内 > 新建应用内消息。
- 找到并选择欢迎消息。
- 将您的受众设置为我们之前使用的 Test Users 分组。

使用应用内消息定位 'Test Users' 分组
如需要,请自定义消息内容。

应用内欢迎消息的自定义示例
将触发器设置为 '应用打开时'。
安排频率。

应用内消息安排选项
使消息生效。
用户识别
之前,我们演示了如何创建移动端订阅。现在我们将扩展到使用 OneSignal SDK 在所有订阅(包括推送、电子邮件和短信)中识别用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件跟踪,以帮助您统一用户并跨平台与他们互动。分配外部 ID
使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码之间一致地识别用户。这确保您的消息传递在各个渠道和第三方系统中保持统一(对集成特别重要)。 每次您的应用识别用户时,使用我们 SDK 的login
方法设置外部 ID。
添加数据标签
标签是字符串数据的键值对,您可以使用它们来存储用户属性(如username
、role
或偏好)和事件(如 purchase_date
、game_level
或用户交互)。标签支持高级消息个性化和分组,允许更高级的用例。
在您的应用中发生事件时,使用我们 SDK 的addTag
和 addTags
方法设置标签。
在这个示例中,用户达到了第 6 级,可以通过名为 current_level
的标签识别,其值设置为 6
。

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

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

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

iOS 和 Android 设备上收到的包含个性化内容的推送通知
添加电子邮件和/或短信订阅
之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。- 使用
addEmail
方法创建电子邮件订阅。 - 使用
addSms
方法创建短信订阅。

通过外部 ID 统一的包含推送、电子邮件和短信订阅的用户档案
- 在添加电子邮件或短信订阅之前获得明确同意。
- 向用户解释每个沟通渠道的好处。
- 提供渠道偏好,让用户可以选择他们偏好的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管控方法:setConsentRequired(true)
:阻止数据收集直到获得同意。setConsentGiven(true)
:一旦获得同意即启用数据收集。
提示推送权限
不要在应用打开时立即调用requestPermission()
,而是采取更策略性的方法。在请求权限之前,使用应用内消息解释推送通知的价值。
有关最佳实践和实现细节,请参阅我们的提示推送权限指南。
监听推送、用户和应用内事件
使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。推送通知事件
addClickListener()
:检测通知被点击时。对深度链接有帮助。addForegroundLifecycleListener()
:控制通知在前台的行为方式。
用户状态变化
addObserver()
用于用户状态:检测外部 ID 设置时。addPermissionObserver()
:跟踪用户与原生推送权限提示的特定交互。addObserver()
用于推送订阅:跟踪推送订阅状态变化时。
应用内消息事件
addClickListener()
:处理应用内点击操作。适用于深度链接或跟踪事件。addLifecycleListener()
:跟踪应用内消息的完整生命周期(显示、点击、关闭等)。
高级设置和功能
探索更多功能以增强您的集成:移动端 SDK 设置和参考
通过查看移动端推送设置指南,确保您已启用所有关键功能。 有关可用方法和配置选项的完整详细信息,请访问移动端 SDK 参考。support@onesignal.com
请包含以下信息:- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息