OSNotification 载荷

`OSNotification` 载荷参考

本页面通过 OSNotification 类解释 OneSignal 推送通知载荷的结构和字段。在移动应用中接收或处理通知时请参考此文档。

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

在您的应用中访问 `OSNotification`

所有 OneSignal SDK 都会触发一个通知事件监听器，返回一个 OSNotification 对象。

Android: OneSignal.setNotificationWillShowInForegroundHandler(...)
iOS: notificationReceivedBlock 或 UNNotificationServiceExtension

使用此对象访问通知标题、正文、数据和其他属性。 OSNotification 类提供在 SDK 通知事件监听器中可访问的所有通知载荷数据。它将原始的 OSNotification 和 OSNotificationPayload 类合并为一个基于 getter 的单一接口。

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 = 公开`、`0 = 私密`、`-1 = 机密`。
`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 设置的自定义键值数据。最多 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 载荷的根目录中，以便在自定义处理程序中更容易访问。

在应用设置中启用使用更新应用 API并设置：

{
  "additional_data_is_root_payload": true
}

使用 data 发送推送它将在 APNS 载荷的根目录中可用。示例：

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

现在您可以直接访问 promo_code 而无需检查自定义字典。

恢复的通知

重启或应用重启后，Android SDK 将恢复通知。

属性	类型	描述
`restoring`	`boolean`	如果通知在设备/应用重启后被恢复，则为 `true`。

可以使用 restoring 标志跳过恢复的通知。为避免恢复旧内容，请在您的通知上设置短或 0 TTL（生存时间）。

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

OSNotification 载荷