OSNotification 载荷

OSNotification 类表示 OneSignal SDK 中的推送通知载荷。在应用中处理通知时，可使用它访问通知标题、正文、自定义数据和平台特定属性。

推送通知载荷限制为 4096 字节。为防止截断，请将载荷保持在 3500 字节以下。additionalData 字段限制为 2048 字节。

在您的应用中访问 `OSNotification`

所有 OneSignal SDK 都提供一个通知事件监听器，返回一个 OSNotification 对象：

Android: 使用通知生命周期监听器
iOS: 使用通知生命周期监听器或 UNNotificationServiceExtension

Android 字段

Property	Type	Description
`getBody()`	`String`	通知的正文文本。
`getTitle()`	`String`	通知的标题。
`getLaunchURL()`	`String`	点击通知时打开的 URL。
`getNotificationId()`	`String`	OneSignal 通知 UUID。
`getAdditionalData()`	`JSONObject`	通过仪表板或 REST API 设置的自定义键值数据。最多 2048 字节。
`getTemplateId()`	`String`	模板 UUID，如果使用模板发送。
`getAndroidNotificationId()`	`int`	Android 原生通知 ID。
`getLargeIcon()`	`String`	大图标的 URL 或资源名称。
`getSmallIcon()`	`String`	小图标资源名称。
`getSmallIconAccentColor()`	`String`	ARGB 格式的图标强调色。
`getSound()`	`String`	播放的声音资源名称。
`getCollapseId()`	`String`	通知替换的折叠键。
`getPriority()`	`int`	Android 优先级（-2 到 2）。
`getLedColor()`	`String`	ARGB 格式的 LED 颜色。
`getLockScreenVisibility()`	`int`	锁屏可见性：`1 = public`、`0 = private`、`-1 = secret`。
`getFromProjectNumber()`	`String`	发送者项目编号。
`getGroupedNotifications()`	`List<OSNotification>`	包含在摘要中的通知。
`getGroupKey()`	`String`	摘要中使用的组键。
`getGroupMessage()`	`String`	摘要文本。
`getBackgroundImageLayout()`	`BackgroundImageLayout`	背景图像布局和文本颜色的对象。
`getActionButtons()`	`List<ActionButton>`	带有图标、文本和 ID 的操作按钮。
`getRawPayload()`	`String`	载荷的完整原始 JSON 字符串。

iOS 字段

Property	Type	Description
`body`	`NSString`	通知的正文文本。
`title`	`NSString`	通知的标题。
`launchURL`	`NSString`	点击通知时打开的 URL。
`notificationId`	`NSString`	OneSignal 通知 UUID。
`additionalData`	`Dictionary`	通过仪表板或 REST API 设置的自定义键值 `data`。最多 2048 字节。
`templateId`	`NSString`	模板 UUID，如果使用模板发送。
`subtitle`	`NSString`	副标题文本。
`category`	`NSString`	iOS 类别标识符。
`threadId`	`NSString`	用于将通知分组为线程（iOS 10+）。
`badge`	`NSInteger`	绝对徽章值。
`badgeIncrement`	`NSInteger`	徽章增量数量。
`contentAvailable`	`BOOL`	如果 `content-available=1`，触发后台获取。
`mutableContent`	`BOOL`	如果 `mutable-content=1`，触发通知服务扩展。
`actionButtons`	`NSArray`	iOS 操作按钮。
`rawPayload`	`NSDictionary`	载荷的完整原始 JSON。
`parseWithApns`	Method	将原始 APNS 载荷转换为 OSNotification。在服务扩展中使用。

`OSNotificationAction`（点击事件）

描述用户与通知的交互。

Property	Type	Description
`actionId`	`String`	被点击的操作按钮的 ID。
`type`	`enum`	`Opened`（默认点击）或 `ActionTaken`（按钮点击）。

自定义 OneSignal 载荷结构

所有 OneSignal 通知在载荷中都包含一个特殊的 "custom" 对象：

{
  "custom": {
    "i": "the-notification-id"
  }
}

此键是 OneSignal SDK 处理通知所必需的。如果缺少，通知将不会触发点击事件或分析。如果您从其他服务向同时使用 OneSignal 的设备发送推送，请通过此键进行过滤以防止重复处理。详见推送载荷处理。

将 additionalData 移至 APNS 根目录

对于 iOS 应用，您可以将 additionalData 字段放置在 APNS 载荷的根目录中，而非 custom 字典内部。这样可以简化在自定义通知处理程序中的访问方式。 1. 通过 API 启用 使用更新应用 API并设置：

{
  "additional_data_is_root_payload": true
}

2. 发送带有 data 的推送 data 字段将出现在 APNS 根载荷中：

{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}

现在您可以直接访问 promo_code，无需检查 custom 字典。

恢复的通知（Android）

Android SDK 会在设备重启或应用重启后恢复通知。

Property	Type	Description
`restoring`	`boolean`	如果通知在设备/应用重启后被恢复，则为 `true`。

检查 restoring 标志以跳过恢复的通知。若要完全阻止旧通知恢复，请在发送时设置较短或为 0 的 TTL（生存时间）。

推送令牌格式

iOS Push (APNS)：64 个字符，仅限十六进制（0-9, a-f）。deviceToken.map {String(format: "%02x", $0)}.joined()
Android Push (FCM)：通常为 163 个字符，字母数字，可能包含连字符、冒号和下划线。

常见问题

最大载荷大小是多少？

推送通知载荷总计限制为 4096 字节。additionalData 字段限制为 2048 字节。为避免截断，请将总载荷保持在 3500 字节以下。

如何在原始载荷中识别 OneSignal 通知？

所有 OneSignal 通知都包含一个 "custom" 对象，其中有一个包含通知 ID 的 "i" 键。通过检查此键可将 OneSignal 通知与其他提供商发送的通知区分开来。

是否可以在 APNS 根载荷中访问 additionalData？

可以。通过更新应用 API 启用 additional_data_is_root_payload，即可将 additionalData 字段放置在 APNS 根目录中，而非 custom 字典内部。详见将 additionalData 移至 APNS 根目录。

Android 通知类别

为 Android 8.0+ 设备配置通知渠道。

移动服务扩展

添加富媒体、徽章和已确认送达跟踪。

移动 SDK 参考

OneSignal 移动 SDK 方法和监听器的完整参考。

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

OSNotification 载荷

在您的应用中访问 `OSNotification`

Android 字段

iOS 字段

`OSNotificationAction`（点击事件）

自定义 OneSignal 载荷结构

将 additionalData 移至 APNS 根目录

恢复的通知（Android）

推送令牌格式

常见问题

最大载荷大小是多少？

如何在原始载荷中识别 OneSignal 通知？

是否可以在 APNS 根载荷中访问 additionalData？

Android 通知类别

移动服务扩展

移动 SDK 参考

​在您的应用中访问 OSNotification

​Android 字段

​iOS 字段

​OSNotificationAction（点击事件）

​自定义 OneSignal 载荷结构

​将 additionalData 移至 APNS 根目录

​恢复的通知（Android）

​推送令牌格式

​常见问题

​最大载荷大小是多少？

​如何在原始载荷中识别 OneSignal 通知？

​是否可以在 APNS 根载荷中访问 additionalData？

Android 通知类别

移动服务扩展

移动 SDK 参考

在您的应用中访问 `OSNotification`

Android 字段

iOS 字段

`OSNotificationAction`（点击事件）

自定义 OneSignal 载荷结构

将 additionalData 移至 APNS 根目录

恢复的通知（Android）

推送令牌格式

常见问题

最大载荷大小是多少？

如何在原始载荷中识别 OneSignal 通知？

是否可以在 APNS 根载荷中访问 additionalData？