跳转到主要内容
OSNotification 类表示 OneSignal SDK 中的推送通知载荷。在应用中处理通知时，可使用它访问通知标题、正文、自定义数据和平台特定属性。
推送通知载荷限制为 4096 字节。为防止截断，请将载荷保持在 3500 字节以下。additionalData 字段限制为 2048 字节。

​
在您的应用中访问 OSNotification

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

​
Android 字段

PropertyTypeDescription
getBody()String通知的正文文本。
getTitle()String通知的标题。
getLaunchURL()String点击通知时打开的 URL。
getNotificationId()StringOneSignal 通知 UUID。
getAdditionalData()JSONObject通过仪表板或 REST API 设置的自定义键值数据。最多 2048 字节。
getTemplateId()String模板 UUID，如果使用模板发送。
getAndroidNotificationId()intAndroid 原生通知 ID。
getLargeIcon()String大图标的 URL 或资源名称。
getSmallIcon()String小图标资源名称。
getSmallIconAccentColor()StringARGB 格式的图标强调色。
getSound()String播放的声音资源名称。
getCollapseId()String通知替换的折叠键。
getPriority()intAndroid 优先级（-2 到 2）。
getLedColor()StringARGB 格式的 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 字段

PropertyTypeDescription
bodyNSString通知的正文文本。
titleNSString通知的标题。
launchURLNSString点击通知时打开的 URL。
notificationIdNSStringOneSignal 通知 UUID。
additionalDataDictionary通过仪表板或 REST API 设置的自定义键值 data。最多 2048 字节。
templateIdNSString模板 UUID，如果使用模板发送。
subtitleNSString副标题文本。
categoryNSStringiOS 类别标识符。
threadIdNSString用于将通知分组为线程（iOS 10+）。
badgeNSInteger绝对徽章值。
badgeIncrementNSInteger徽章增量数量。
contentAvailableBOOL如果 content-available=1，触发后台获取。
mutableContentBOOL如果 mutable-content=1，触发通知服务扩展。
actionButtonsNSArrayiOS 操作按钮。
rawPayloadNSDictionary载荷的完整原始 JSON。
parseWithApnsMethod将原始 APNS 载荷转换为 OSNotification。在服务扩展中使用。

​
OSNotificationAction（点击事件）

描述用户与通知的交互。
PropertyTypeDescription
actionIdString被点击的操作按钮的 ID。
typeenumOpened（默认点击）或 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 会在设备重启或应用重启后恢复通知。
PropertyTypeDescription
restoringboolean如果通知在设备/应用重启后被恢复，则为 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 方法和监听器的完整参考。