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

# 推送概览

> 通过 OneSignal 仪表板或 API 发送和管理移动端和 Web 推送通知，支持定向、个性化和计划发送。

推送通知通过及时、个性化的内容跨设备重新吸引用户——即使他们没有主动使用您的应用或网站。

观看推送通知如何驱动最高参与度，或跳过直接开始。

<Frame caption="推送通知为何能驱动最高参与度">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/atjjj4BQqfc?si=PP-XrMF8ttXkXkuQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

OneSignal 提供一个完整平台来管理移动端、Web 和桌面端的推送通知：

* **从[仪表板](#send-push-notifications)或 [API](/reference/create-message) 发送营销活动和事务消息**
* **通过 [Journeys](./journeys-overview) 自动化多渠道流程**
* **使用[细分](./segmentation)、过滤器或用户数据精确定向用户**
* **[A/B 测试](./ab-testing)并优化**消息性能
* **用用户属性和[动态内容](./message-personalization)个性化内容**
* **与您的技术栈集成** — HubSpot、Mixpanel、Amplitude、Zapier 及[更多](./integrations)

***

## 推送设置

在发送推送通知之前，完成平台设置、配置权限提示并启用所需功能。

### 平台设置指南

<Columns cols={2}>
  <Card title="移动推送设置" icon="mobile" href="./mobile-push-setup">
    iOS、Android、华为和亚马逊推送通知的端到端设置。
  </Card>

  <Card title="网页推送设置" icon="globe" href="./web-push-setup">
    为 Chrome、Firefox、Safari 和 Edge 启用推送。
  </Card>

  <Card title="移动 SDK 设置" icon="code" href="./mobile-sdk-setup">
    将 OneSignal SDK 集成到您的移动应用中。
  </Card>

  <Card title="网页 SDK 设置" icon="browsers" href="./web-sdk-setup">
    将 OneSignal SDK 集成到您的网站中。
  </Card>

  <Card title="迁移到 OneSignal" icon="arrow-right-arrow-left" href="./migrating-to-onesignal">
    从 Firebase、Airship、Braze 和其他提供商迁移的步骤。
  </Card>

  <Card title="macOS 应用支持" icon="desktop" href="./macos-app-setup">
    为 macOS 应用配置 OneSignal。
  </Card>

  <Card title="Windows 应用支持" icon="desktop" href="./windows-app-setup">
    为 Windows 桌面应用配置 OneSignal。
  </Card>

  <Card title="watchOS 和 Wear OS 支持" icon="clock" href="./watchos-and-wear-os-support">
    将 OneSignal 添加到 Apple Watch 和 Wear OS 设备。
  </Card>
</Columns>

### 权限

精心设计的选择加入体验能最大化您的推送受众。

<Columns cols={2}>
  <Card title="移动推送提示" icon="bell" href="./prompt-for-push-permissions">
    为移动应用构建预权限提示和最佳实践。
  </Card>

  <Card title="网页推送提示" icon="bell-on" href="./permission-requests">
    自定义网页推送的提示时机和消息。
  </Card>

  <Card title="iOS 临时推送" icon="apple" href="./ios-provisional-push-notifications">
    在请求完整权限之前，向通知中心发送静默通知。
  </Card>

  <Card title="Android 通知类别" icon="android" href="./android-notification-categories">
    让 Android 用户自定义接收您应用通知的方式。
  </Card>
</Columns>

### 功能和高级用例

<Columns cols={2}>
  <Card title="消息个性化" icon="wand-magic-sparkles" href="./message-personalization">
    添加动态内容为每个用户个性化消息。
  </Card>

  <Card title="多语言消息" icon="language" href="./multi-language-messaging">
    以每位用户的首选语言发送推送通知。
  </Card>

  <Card title="限流" icon="gauge-high" href="./throttling">
    控制大量受众的通知推送速度。
  </Card>

  <Card title="频率限制" icon="hand" href="./frequency-capping">
    限制每位用户的推送通知数量。
  </Card>

  <Card title="数据和后台通知" icon="database" href="./data-notifications">
    为后台任务发送纯数据通知。
  </Card>

  <Card title="VoIP 通知" icon="phone" href="./voip-notifications">
    为通话应用发送 VoIP 专属推送通知。
  </Card>
</Columns>

***

## 发送推送通知

您可以通过多种方式发送消息。最佳选择取决于您的使用场景。

<Columns cols={2}>
  <Card title="仪表板" icon="window-maximize" href="#send-from-the-dashboard">
    在仪表板中快速撰写消息。
  </Card>

  <Card title="通过 API 发送" icon="code" href="/reference/create-message">
    使用 REST API 以编程方式发送消息。
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    构建自动化的多步骤和多渠道流程。
  </Card>

  <Card title="A/B 测试" icon="flask" href="./ab-testing">
    测试多达 10 种消息变体以优化性能。
  </Card>
</Columns>

### 从仪表板发送

<Steps>
  <Step title="选择消息渠道" icon="window-maximize">
    选择 **创建...** 然后选择您的消息渠道。您也可以导航到 **消息** 或 **模板** 查看历史消息。

    <Frame caption="在 OneSignal 仪表板中创建新消息。">
      <img src="https://mintcdn.com/onesignal/UDk6E5NjA3sdGdRN/images/dashboard/create-message.png?fit=max&auto=format&n=UDk6E5NjA3sdGdRN&q=85&s=97504cf71555ac4aeb263a36ad2d28b3" alt="OneSignal 仪表板显示创建消息选项" width="2128" height="1374" data-path="images/dashboard/create-message.png" />
    </Frame>
  </Step>

  <Step title="选择编辑方式" icon="pencil">
    * 从头开始或使用 [AI 消息编写器](./ai-message-composer)。
    * 使用预构建的[模板](./templates)
  </Step>

  <Step title="设置名称和标签" icon="tag">
    添加用于跟踪和报告的内部元数据。API 等效参数：`name`
  </Step>

  <Step title="选择受众" icon="users">
    选择接收消息的用户。您可以包含和排除[细分](./segmentation)来定向特定群体。未设置细分时，默认发送给所有"已订阅用户"。

    <Frame caption="仪表板中的名称、标签和受众细分选择。">
      <img src="https://mintcdn.com/onesignal/ciRrThfP6xMpI7GY/images/dashboard/message-name-label-audience.png?fit=max&auto=format&n=ciRrThfP6xMpI7GY&q=85&s=1f41b0e42d31211b1c1badf87ba84056" alt="仪表板中消息名称、标签和受众细分选择字段" width="1650" height="518" data-path="images/dashboard/message-name-label-audience.png" />
    </Frame>

    | 定向方式                                         | 仪表板 | API |
    | -------------------------------------------- | :-: | :-: |
    | [**细分**](./segmentation)                     |  是  |  是  |
    | **过滤器**（[仅限 API](/reference/create-message)） |  否  |  是  |
    | **别名**（[仅限 API](/reference/create-message)）  |  否  |  是  |
  </Step>
</Steps>

### 投递时间安排和优化

查看时机如何影响推送通知性能。

<Frame caption="时机就是一切：如何发送能驱动行动的推送通知">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/pRTbUuvYsWY?si=uqL5wSK_vXH6VwMJ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

选择消息开始发送的时间。

| 选项       | 描述                 | API 字段       |
| -------- | ------------------ | ------------ |
| **立即发送** | 立即投递给所有收件人。        | —            |
| **定时发送** | 在特定时间发送，最多提前 30 天。 | `send_after` |

**按用户优化：**

设置用户何时接收消息。

| 选项                                | 描述                   | API 字段                                            |
| --------------------------------- | -------------------- | ------------------------------------------------- |
| **同时发送给所有人**                      | 所有收件人同时收到消息。最适合紧急消息。 | —                                                 |
| **智能投递**                          | 根据用户会话活动在最佳时间发送。     | `delayed_option: last-active`                     |
| **按时区自定义时间**                      | 在每个用户时区的设定本地时间发送。    | `delayed_option: timezone`、`delivery_time_of_day` |
| **覆盖[限流](./throttling)**          | 更改限流速率。              | `throttle_rate_per_minute`                        |
| **覆盖[频率限制](./frequency-capping)** | 为此消息禁用频率限制。          | `enable_frequency_cap`                            |

### 设计属性

推送消息可以显示面向用户的内容，也可以执行后台操作。

* **显示通知**：需要[消息](#message)，可以包含标题、图片、操作按钮和其他视觉元素。
* **后台/纯数据通知**：省略消息，包含 [content\_available](./data-notifications)，可选包含[附加数据](#additional-data)。

<Frame caption="1：标题，2：消息，3：图标，4：图片，5：操作按钮，6：应用名称或浏览器，7：接收时间戳">
  <img src="https://mintcdn.com/onesignal/l4Z9oMlZl9nJOS_T/images/push/web-and-mobile-push-notifications-anatomy.jpg?fit=max&auto=format&n=l4Z9oMlZl9nJOS_T&q=85&s=abd46b4656559360cc713cfa98f138fe" alt="展示 Web 和移动端推送通知结构的标注图" width="1468" height="2302" data-path="images/push/web-and-mobile-push-notifications-anatomy.jpg" />
</Frame>

<Tip>
  使用 [AI 消息编写器](./ai-message-composer) 快速生成通知标题和正文。只需几次点击，即可调整语调和内容以匹配您的品牌。
</Tip>

#### 标题

通知最顶部的可自定义文本。文本外观由操作系统控制。

* **网页推送**和**华为**必需
* 未设置时在网页上默认为网站名称
* 建议限制：25–50 个字符（移动端），60–80 个字符（网页）
* 支持：[AI 消息编写器](./ai-message-composer)、表情符号、[消息个性化](./message-personalization)、[多语言消息](./multi-language-messaging)
* API：`headings`

#### 副标题

仅在 iOS 和 macOS 上支持的次要文本（通过 APNs）。在 Android 或网页上不可用。

* 建议限制：25–50 个字符
* 支持：表情符号、[消息个性化](./message-personalization)、[多语言消息](./multi-language-messaging)
* API：`subtitle`

#### 消息

通知的主要内容。不支持自定义字体或样式。样式由操作系统设置。

* 除非发送后台通知，否则为必需
* 支持：[AI 消息编写器](./ai-message-composer)、表情符号、[消息个性化](./message-personalization)、[多语言消息](./multi-language-messaging)
* 建议限制：约 150 个字符
* API：`contents`

#### 图标

在 Android 和网页上自定义小图标和大图标。iOS 始终使用应用图标。

* 参见[通知图标](./notification-icons)

#### 图片

在 Android、iOS 和 Windows/Android 版 Chrome 的通知中添加大图片。

* 建议尺寸：`1024×512px`（2:1 纵横比）
* 最大尺寸：1 MB，最大宽度：2000 px
* Safari（macOS/iOS）或 macOS 通知中心不支持
* 在移动端需要点击或展开才能查看
* 支持格式：`PNG`、`JPG`、`GIF`（仅 iOS 支持动画）
* API：`ios_attachments`（iOS）、`big_picture`（Android）、`chrome_web_image`（Chrome 网页）
* 参见[图片和富媒体](./rich-media)

#### 应用名称

显示通知的应用名称。

* **iOS**：在 Xcode 的 *Display Name* 下设置；更新需重启设备
* **Android/亚马逊/华为**：在 `AndroidManifest.xml` 的 `<application android:label="YOUR APP NAME">` 下设置
* **网页**：显示网站名称和/或浏览器

### 功能属性

#### 操作按钮

向推送通知添加交互式按钮。

* 支持 Android 4.1+ 和 iOS 8.0+
* 参见[操作按钮](./action-buttons)

#### 启动 URL

控制用户点击通知时的跳转目标。

* API：`url`（单个通用 URL）、`app_url`（深度链接，例如 `your-app://screen`）、`web_url`（http/https 网页链接）
* 参见 [URL、链接和深度链接](./links)

#### 徽章

在应用图标上显示圆点或徽章数字。

* **iOS**：红色数字徽章；可设置、增加或清除。API：`ios_badgeType`、`ios_badgeCount`
* **Android**：需要[通知类别](./android-notification-categories)
* **华为**：徽章显示为数字或圆点。API：`huawei_badge_class`、`huawei_badge_set_num`、`huawei_badge_add_num`
* **Web（Chrome/Android）**：Android 状态栏中显示的图标；必须是 72×72 alpha PNG。API：`chrome_web_badge`
* 参见[徽章](./badges)

#### 声音

推送送达时播放声音。

* **iOS**：使用 `sound` 设置
* **Android**：通过[通知类别](./android-notification-categories)设置
* **网页**：不可用

#### 附加数据

向载荷添加自定义键值对供 SDK 处理。

* 适用于[移动服务扩展](./service-extensions)以及[移动 SDK](./mobile-sdk-reference) 和[网页 SDK](./web-sdk-reference) 中的点击监听器
* 仪表板仅支持简单的键值数据；发送嵌套 JSON 请使用带有 `data` 的 API
* 最大总载荷：约 4 KB；`data` 字段：最多 2048 字节
* 参见[通知载荷参考](./osnotification-payload)

#### Collapse ID（移动推送）

如果共享相同的 `collapse_id`，则用更新的通知替换早期通知。最大长度：64 个字符。API：`collapse_id`

例如，天气应用发送三条预警。如果用户在三条全部发送后才打开设备，则只显示最后一条消息。

#### 网页推送主题（网页推送）

通过使用唯一的 `web_push_topic` 值避免替换旧的网页通知。具有不同主题的通知将独立保持可见。最大长度：64 个字符。API：`web_push_topic`

#### 优先级

设置推送的紧急程度，特别是在省电模式下。

* **高**（推荐）：即时、基于警报的消息
* **普通**：用于后台/数据通知
* API：`priority`
* 平台文档：[APNs 优先级](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns)、[FCM 优先级](https://firebase.google.com/docs/cloud-messaging/android/message-priority)

#### 存活时间（TTL）

设备离线时消息的保留时长。默认：3 天。范围：0–2,419,200 秒（28 天）。API：`ttl`

如果用户离线且 TTL 过期，消息将被丢弃。将 `ttl: 0` 设置为永不延迟送达的消息。

<Note>
  **iOS 限制**：APNs 在设备离线时仅存储**最新**的通知。早期通知会被丢弃。[了解更多](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW5)。
</Note>

#### 通知分组

当设备收到来自您应用的 4 条或更多通知后，Android 和 iOS 会自动分组通知。

* **iOS**：在 API 中使用 `thread_id` 将消息归入同一组。
* **Android**：在 API 中使用 `android_group`，或在仪表板中设置"组键"。如需高级自定义，参见 [Android NotificationExtenderService](./service-extensions#android-notification-extender-service) 和 [Android 分组通知指南](https://developer.android.com/training/notify-user/group)。

<Frame caption="Android 上的分组通知。">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/GnEw4PmmSVWWfgX5Uc3W_stacked_notification.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=cee04b5675b291562d92add259bc2224" alt="Android 设备显示来自同一应用的分组推送通知" width="900" height="460" data-path="images/docs/GnEw4PmmSVWWfgX5Uc3W_stacked_notification.png" />
</Frame>

***

## 取消推送通知

如果消息尚未**送达**，可以取消它。OneSignal 将停止向所有尚未加入队列的订阅发送消息。这不会从已收到消息的设备上删除消息。

在[消息报告](./push-notification-message-reports)中，选择**操作 > 取消**，或使用[取消消息 API](/reference/cancel-message)。

### 从设备移除推送通知

消息送达后，仅在设置了 [Collapse ID](#collapse-id-mobile-push) 或[网页推送主题](#web-push-topic-web-push) 的情况下，才能替换推送通知。未设置这两项时，通知无法被替换或移除。

***

## 分析

跟踪消息性能和参与度。

<Columns cols={2}>
  <Card title="推送消息报告" icon="chart-line" href="./push-notification-message-reports">
    消息级别的送达率、打开率和点击率报告。
  </Card>

  <Card title="分析概览" icon="chart-bar" href="./analytics-overview">
    OneSignal 中所有可用的分析选项。
  </Card>

  <Card title="事件流" icon="signal-stream" href="./event-streams">
    实时将推送事件流式传输到您的数据仓库或 BI 工具。
  </Card>

  <Card title="查看消息 API" icon="code" href="/reference/view-messages">
    通过 REST API 以编程方式提取消息分析数据。
  </Card>
</Columns>

***

## 常见问题

### OneSignal 推送支持哪些平台？

OneSignal 支持 iOS（APNs）、Android（FCM）、华为（HMS）、亚马逊（ADM）、网页浏览器（Chrome、Firefox、Safari、Edge）、macOS 和 Windows 上的推送。参见上方的[平台设置指南](#platform-setup-guides)。

### 发送给用户之前如何测试推送通知？

设置[测试订阅](./test-users)来验证送达、渲染和深度链接，而不影响真实用户。您也可以发送到单用户细分进行快速测试。

### 为什么我的推送通知没有显示？

常见原因包括平台凭据缺失或过期、用户未授予权限，或设备级别的设置（如勿扰模式）。完整的故障排除清单请参见[通知未显示或延迟](./notifications-show-successful-but-are-not-being-shown)。

### 推送通知的最大载荷大小是多少？

所有平台的总载荷大小约为 4 KB。`data` 字段最多支持 2048 字节。超出这些限制可能导致通知被截断或拒绝。