> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OSNotification 载荷

> OneSignal OSNotification 对象的参考，包括所有载荷字段、Android 和 iOS 特定属性、自定义数据和点击操作。

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

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

***

## 在您的应用中访问 `OSNotification`

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

* **Android**: 使用[通知生命周期监听器](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS**: 使用[通知生命周期监听器](./mobile-sdk-reference#addforegroundlifecyclelistener-push)或 `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"` 对象：

```json theme={null}
{
  "custom": {
    "i": "the-notification-id"
  }
}
```

<Info>
  此键是 OneSignal SDK 处理通知所必需的。如果缺少，通知将不会触发点击事件或分析。如果您从其他服务向同时使用 OneSignal 的设备发送推送，请通过此键进行过滤以防止重复处理。详见[推送载荷处理](./migrating-to-onesignal#push-payload-handling)。
</Info>

***

## 将 additionalData 移至 APNS 根目录

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

**1. 通过 API 启用**

使用[更新应用 API](/reference/update-an-app)并设置：

```json theme={null}
{
  "additional_data_is_root_payload": true
}
```

**2. 发送带有 `data` 的推送**

`data` 字段将出现在 APNS 根载荷中：

```json theme={null}
{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}
```

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

***

## 恢复的通知（Android）

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

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

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

***

## 推送令牌格式

* **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](/reference/update-an-app) 启用 `additional_data_is_root_payload`，即可将 `additionalData` 字段放置在 APNS 根目录中，而非 `custom` 字典内部。详见[将 additionalData 移至 APNS 根目录](#move-additionaldata-to-apns-root)。

***

<Columns cols={3}>
  <Card title="Android 通知类别" icon="android" href="./android-notification-categories">
    为 Android 8.0+ 设备配置通知渠道。
  </Card>

  <Card title="移动服务扩展" icon="puzzle-piece" href="./service-extensions">
    添加富媒体、徽章和已确认送达跟踪。
  </Card>

  <Card title="移动 SDK 参考" icon="code" href="./mobile-sdk-reference">
    OneSignal 移动 SDK 方法和监听器的完整参考。
  </Card>
</Columns>