iOS SDK 设置 - OneSignal

概述

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)。

如果您的组织已有 OneSignal 账户，请申请加入组织。否则，请注册免费账户以开始使用。

分步设置说明

创建或选择您的应用

点击 新应用/网站 创建新应用，或在 设置 > 推送和应用内 中向现有应用添加平台。选择您要配置的平台，然后点击 下一步：配置您的平台。

OneSignal 控制台显示包含组织名称、应用名称和频道选择的新应用设置流程 — 设置您的第一个 OneSignal 应用、组织和频道。

配置平台凭据

为您的平台输入凭据：

输入您的凭据后点击 保存并继续。

保存您的应用 ID 并安装 SDK

您的 应用 ID 显示在最终屏幕上。复制并保存它——初始化 SDK 时需要使用它。选择您的 SDK 平台，然后按照设置指南操作。

OneSignal 控制台显示设置完成后的应用 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。

您的应用组名称必须完全匹配您在所有目标中的包 ID 拼写和大小写。

打开您应用的 Info.plist
添加新属性：

键： OneSignal_app_groups_key
值：您现有的应用组名称（例如，group.com.example.mycustomgroup）

XML

<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)
        }
    }
}

#import <OneSignalExtension/OneSignalExtension.h>
#import "NotificationService.h"

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNNotificationRequest *receivedRequest;
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

// Note, this extension only runs when mutable-content is set
// 设置附件或操作按钮会自动添加此项
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.receivedRequest = request;
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
//     NSLog(@"Running NotificationServiceExtension");
//     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

    [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                       withMutableNotificationContent:self.bestAttemptContent
                                   withContentHandler:self.contentHandler];
}

- (void)serviceExtensionTimeWillExpire {
    // 将此作为交付修改内容的"最佳尝试"的机会，否则将使用原始推送载荷。

    [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

    self.contentHandler(self.bestAttemptContent);
}

@end

您应该会看到一个错误，因为 OneSignal 包尚未安装。这将在下一步中解决。

SDK设置

本部分将指导您集成 OneSignal 的核心功能。在本部分结束时，您将拥有与我们 SDK 的基本集成，使您能够触发应用内消息并接收推送通知。

1. 添加 SDK

使用 Xcode Package Dependencies Manager (Swift Package Manager) 或 CocoaPods 添加我们的 SDK。有 4 个可用的库。如果您不需要应用内消息和/或位置追踪，您可以省略这些包。

库	目标	必需
OneSignalExtension	OneSignalNotificationServiceExtension	✅
OneSignalFramework	App	✅
OneSignalInAppMessages	App	推荐
OneSignalLocation	App	可选

Xcode 包依赖
CocoaPods

导航到 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 并添加以下内容：

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
Storyboard

如果使用 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 类的剩余内容...
}

#import <OneSignalFramework/OneSignalFramework.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // 启用详细日志记录以便调试（在生产中移除）
  [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];
  // 使用您的 OneSignal App ID 初始化
  [OneSignal initialize:@"YOUR_APP_ID" withLaunchOptions:launchOptions];
  // 使用此方法提示推送通知。
  // 我们建议在测试后移除此方法，而改用应用内消息提示通知权限。
  [OneSignal.Notifications requestPermission:^(BOOL accepted) {
    NSLog(@"User accepted notifications: %d", accepted);
  } fallbackToSettings:false];

  // 使用 externalId 登录您的客户
  // [OneSignal login:@"EXTERNAL_ID"];

  return YES;
}

禁用方法 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

// In application:didFinishLaunchingWithOptions:, BEFORE [OneSignal initialize:]
[UNUserNotificationCenter currentNotificationCenter].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)
}

- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [OneSignal.Notifications didRegisterForRemoteNotifications:application deviceToken:deviceToken];
}

- (void)application:(UIApplication *)application
    didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [OneSignal.Notifications handleDidFailRegisterForRemoteNotification:error];
}

后台/静默通知：

func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    OneSignal.Notifications.receiveRemoteNotification(application,
                                                      userInfo: userInfo,
                                                      completionHandler: completionHandler)
}

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [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([])
        }
    }
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    [OneSignal.Notifications
        handleWillPresentNotificationInForegroundWithPayload:notification.request.content.userInfo
        withCompletion:^(OSNotification *notif) {
            if (notif) {
                if (@available(iOS 14.0, *)) {
                    completionHandler(UNNotificationPresentationOptionBanner |
                                      UNNotificationPresentationOptionList |
                                      UNNotificationPresentationOptionSound);
                } else {
                    completionHandler(UNNotificationPresentationOptionAlert |
                                      UNNotificationPresentationOptionSound);
                }
            } else {
                completionHandler(UNNotificationPresentationOptionNone);
            }
        }];
}

onWillDisplayNotification 生命周期监听器和 preventDefault / display API 继续支持手动转发。SDK 从 handleWillPresentNotificationInForegroundWithPayload 内部调用您的监听器。

通知点击/操作：

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    OneSignal.Notifications.handleNotificationResponse(response)
    completionHandler()
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
    didReceiveNotificationResponse:(UNNotificationResponse *)response
             withCompletionHandler:(void (^)(void))completionHandler {
    [OneSignal.Notifications handleNotificationResponse:response];
    completionHandler();
}

可选：设置角标数量

禁用 swizzling 后，SDK 无法拦截角标变化。使用此方法设置角标数量并与 OneSignal 的内部角标缓存保持同步：

OneSignal.Notifications.setBadgeCount(5)

[OneSignal.Notifications setBadgeCount:5];

SwiftUI 应用

SwiftUI 应用默认没有 AppDelegate。使用 @UIApplicationDelegateAdaptor 添加一个，然后实现上面所示的所有转发方法：

Swift

@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 向分组发送了通知。

没有收到图片？您的通知服务扩展可能缺失。
没有确认送达？请检查您的应用组设置。
遇到问题？将 API 请求和应用启动从开始到结束的日志复制粘贴到 .txt 文件中。然后将两者都发送给 support@onesignal.com。

发送应用内消息

应用内消息让您可以在用户使用您的应用时与他们进行沟通。

在设备上关闭或将您的应用切换到后台。

这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中，当用户在应用处于后台或关闭至少 30 秒后重新打开应用时，会开始一个新会话。更多详情，请参阅我们的应用内消息如何显示指南。

创建应用内消息。

在您的 OneSignal 控制台中，导航到 消息 > 应用内 > 新建应用内消息。
找到并选择欢迎消息。
将您的受众设置为我们之前使用的 Test Users 分组。

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

将触发器设置为 '应用打开时'。

安排频率。

在 安排 > 您希望多久显示一次此消息？ 下选择 每次触发条件满足时。

使消息生效。

点击 使消息生效，这样每次测试用户打开应用时都可以使用该消息。

打开应用并查看消息。

应用内消息生效后，打开您的应用。您应该会看到它显示：

没有看到消息？

开始新会话
- 您必须关闭或将应用切换到后台至少 30 秒后再重新打开。这可以确保开始新会话。
- 更多信息，请参阅应用内消息如何显示。
仍在 Test Users 分组中？
- 如果您重新安装或更换了设备，请重新将设备添加到测试订阅并确认它是 Test Users 分组的一部分。
遇到问题？
- 在重现上述步骤时，请遵循获取调试日志。这将生成额外的日志，您可以与 support@onesignal.com 分享，我们将帮助调查正在发生的情况。

您已成功设置 OneSignal SDK 并学习了重要概念，如：

收集订阅，设置测试订阅，以及创建分组。
使用分组和我们的创建消息 API 发送带图片的推送和确认送达。
发送应用内消息。

继续阅读本指南以在您的应用中识别用户并设置其他功能。

用户识别

之前，我们演示了如何创建移动端订阅。现在我们将扩展到使用 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。

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

我们可以创建一个等级在 5 到 10 之间的用户分组，并使用它来发送有针对性的个性化消息：

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

添加电子邮件和/或短信订阅

之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。

使用addEmail 方法创建电子邮件订阅。
使用addSms 方法创建短信订阅。

如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 会将其添加到现有用户，不会创建重复项。您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。

多渠道沟通的最佳实践

在添加电子邮件或短信订阅之前获得明确同意。
向用户解释每个沟通渠道的好处。
提供渠道偏好，让用户可以选择他们偏好的渠道。

隐私和用户同意

要控制 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（如适用）
任何相关的日志或错误信息

我们很乐意为您提供帮助！

​概述

​要求

​配置您的 OneSignal 应用和平台

​iOS 设置

​1. 向应用目标添加推送通知功能

​2. 向应用目标添加后台模式功能

​3. 将应用目标添加到应用组

​4. 添加通知服务扩展

​5. 将 NSE 目标添加到应用组

​6. 更新 NSE 代码

​SDK设置

​1. 添加 SDK

​2. 初始化 SDK

​禁用方法 swizzling（可选）

​步骤 1. 添加 Info.plist 标志

​步骤 2. 设置 UNUserNotificationCenter 委托

​步骤 3. 转发通知委托方法

​可选：设置角标数量

​SwiftUI 应用

​API 参考

​测试 OneSignal SDK 集成

​检查移动端订阅

​设置测试订阅

​通过 API 发送测试推送

​发送应用内消息

​用户识别

​分配外部 ID

​添加数据标签

​添加电子邮件和/或短信订阅

​隐私和用户同意

​提示推送权限

​监听推送、用户和应用内事件

​推送通知事件

​用户状态变化

​应用内消息事件

​高级设置和功能

​移动端 SDK 设置和参考

概述

要求

配置您的 OneSignal 应用和平台

iOS 设置

1. 向应用目标添加推送通知功能

2. 向应用目标添加后台模式功能

3. 将应用目标添加到应用组

4. 添加通知服务扩展

5. 将 NSE 目标添加到应用组

6. 更新 NSE 代码

SDK设置

1. 添加 SDK

2. 初始化 SDK

禁用方法 swizzling（可选）

步骤 1. 添加 Info.plist 标志

步骤 2. 设置 UNUserNotificationCenter 委托

步骤 3. 转发通知委托方法

可选：设置角标数量

SwiftUI 应用

API 参考

测试 OneSignal SDK 集成

检查移动端订阅

设置测试订阅

通过 API 发送测试推送

发送应用内消息

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

提示推送权限

监听推送、用户和应用内事件

推送通知事件

用户状态变化

应用内消息事件

高级设置和功能

移动端 SDK 设置和参考