> ## 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.

# 数据和后台通知

> 在 iOS 和 Android 上发送静默推送通知，以同步数据或触发后台任务，而不显示可见消息。

## 什么是静默通知？

静默通知可让您唤醒应用并执行后台任务（如同步或刷新数据），而无需显示可见消息或播放声音。

在 iOS 上，这些被称为**后台通知**，在 Android 上，它们被称为**数据通知**。它们统称为静默推送，行为与普通的可见通知不同。

### 限制

* **应用无法接收静默推送**，如果：
  * **iOS**：应用已被用户关闭，例如从应用切换器中滑动删除时。（参见 [Apple 支持](https://support.apple.com/en-us/HT201330)）。
  * **Android**：应用已通过设备设置强制退出，或被某些制造商在滑动删除时自动关闭。（[更多详情](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)）。
* **无法保证送达**：
  * Apple 和 Google 都将静默通知视为*尽力而为*。iOS 可能在低电量模式下、关闭后台应用刷新或应用被用户关闭时延迟或丢弃送达。Android 可能在 Doze 或 OEM 省电规则下限制或批量送达。
  * 因此，**静默通知绝不应用于关键更新**。
* **仅限订阅用户**：OneSignal SDK 仅向订阅的[订阅](./subscriptions)发送数据通知。要触达未订阅用户，请遵循[此解决方案](https://github.com/OneSignal/OneSignal-iOS-SDK/issues/302)。
* **对跨平台 SDK 的有限支持**：
  * 静默通知必须在原生代码中处理（Android 使用 Java/Kotlin，iOS 使用 Swift/Obj-C）。
  * iOS 需要实现 [`application:didReceiveRemoteNotification:fetchCompletionHandler:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application)。
  * Android 需要实现[通知服务扩展](./service-extensions)。

***

## 从 OneSignal 发送静默通知

按照以下步骤从 OneSignal 发送静默通知：

<Steps>
  <Step title="省略可见内容">
    从消息中移除任何可见文本或标题。这包括：

    * **API**：您的 [Create notification](/reference/create-message) API 请求中的 `contents`、`headings`、`subtitle`。
    * **控制台**：消息、标题、副标题
  </Step>

  <Step title="设置 content_available">
    * **API**：将 `content_available` 设置为 `true`。
    * **控制台**：在"发送到 Apple iOS"下勾选 **Content available**。这适用于所有平台，只是告诉我们的系统没有发送消息。
  </Step>

  <Step title="向通知添加数据">
    * **API**：使用 `data` 参数。
    * **控制台**：使用 **Additional Data** 字段。
  </Step>
</Steps>

### API 请求示例

```bash theme={null}
curl -X POST https://api.onesignal.com/notifications \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "external_id": ["user-123"] },
    "target_channel": "push",
    "content_available": true,
    "data": {
      "action": "sync_data",
      "version": "2"
    }
  }'
```

***

## 平台特定设置

### iOS 后台通知设置

要处理后台通知，您的 iOS 应用必须在 Xcode 中启用 **Background Modes > Remote Notifications** 功能。如果您按照我们的[移动 SDK 设置](./mobile-sdk-setup)操作，通常会包含此功能。

要处理通知，请实现 `AppDelegate` 方法 [`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application)。

Apple 文档：

* [Pushing Background Updates to Your App](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app?language=objc)
* [Generating a Remote Notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)

<Warning>
  如果用户关闭了应用（从应用切换器中滑动删除），iOS 将不会送达通知。

  在这种情况下，请包含可见的 `contents` 消息，并在 [`UNNotificationServiceExtension.didReceive`](./service-extensions#ios-notification-service-extension) 中处理数据。
</Warning>

***

### Android 数据通知设置

使用[通知服务扩展](./service-extensions)在 Android 上处理数据通知。

这可以实现：

* 只要应用未被强制关闭，就可以处理通知
* 自定义通知的显示或抑制方式

Android 文档：

* [FCM 数据消息](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)
* [针对 Doze 和应用待机优化](https://developer.android.com/training/monitoring-device-state/doze-standby)

<Warning>
  如果应用已被强制停止（通过设备设置或部分 OEM 电池优化），Android 将不会送达通知。请参阅 [Android 强制停止行为](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)。
</Warning>

***

## 发送 VoIP 通知

支持 VoIP 通知，但需要在标准 OneSignal SDK 之外进行额外配置。OneSignal 不会自动注册 VoIP 令牌。

<Card title="VoIP 通知设置指南" icon="phone" href="./voip-notifications">
  在 iOS 上配置用于实时通话的 VoIP 推送通知。
</Card>

***

## 常见问题

### 静默通知能否用于检测卸载或取消订阅？

从技术上讲可以，但不可靠。如上面[限制](#限制)部分所述，无法保证静默通知的送达。

相反：

* 每月至少向所有用户发送一次可见通知（包含内容）。
* 可选择发送静默通知作为补充检查。

有关处理订阅状态更改的更多详细信息，请参阅我们的[订阅](./subscriptions)指南。

### 确认送达是否适用于静默通知？

确认送达不适用于静默通知。

### 我可以使用静默通知来测量有多少用户可以到达吗？

不可以，不可靠。静默通知无法保证送达。

1. **无法保证送达** — Apple 和 Google 都将静默通知视为尽力而为，可能会延迟或丢弃。例如，如果应用已关闭（强制退出），iOS 将丢弃通知；Android 和 iOS 在省电规则下会限制通知。

2. **无法确认送达** — 确认送达不适用于静默通知，因此您无法知道哪些用户实际收到了推送。

要测量可到达的用户，请发送可见通知并在[分析](./analytics-overview)中跟踪送达指标。

***

<Columns cols={2}>
  <Card title="服务扩展" icon="puzzle-piece" href="./service-extensions">
    在 iOS 和 Android 上以原生代码处理通知。
  </Card>

  <Card title="订阅" icon="address-book" href="./subscriptions">
    了解订阅类型及其与用户的连接方式。
  </Card>

  <Card title="创建消息 API" icon="code" href="/reference/create-message">
    以编程方式发送通知，包括静默推送。
  </Card>
</Columns>