推送概览

推送通知通过及时、个性化的内容跨设备重新吸引用户——即使他们没有主动使用您的应用或网站。 观看推送通知如何驱动最高参与度，或跳转到开始使用。 OneSignal 提供一个完整平台来管理移动端、Web 和桌面端的推送通知：

• 从仪表板或 API 发送营销活动和事务消息
• 通过 Journeys 自动化多渠道流程
• 使用细分、过滤器或用户数据精确定向用户
• A/B 测试并优化消息性能
• 用用户属性和动态内容个性化内容
• 与您的技术栈集成 — HubSpot、Mixpanel、Amplitude、Zapier 及更多

---

​

推送设置

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

​

平台设置指南

​

权限

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

​

功能和高级用例

---

​

发送推送通知

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

​

从仪表板发送

​

投递时间安排和优化

查看时机如何影响推送通知性能。 选择 OneSignal 何时评估受众成员资格并开始投递消息。 按用户投递时间： 设置受众中的每个用户何时接收消息。 投递覆盖： 仅为此消息覆盖应用级别的投递默认值。

​

设计属性

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

• 显示通知：需要消息，可以包含标题、图片、操作按钮和其他视觉元素。
• 后台/纯数据通知：省略 headings 和 contents，在 iOS 和 Android 上都将 content_available 设置为 true，并可选包含附加数据。

图例： 1 标题、2 消息、3 图标、4 图片、5 操作按钮、6 应用名称或浏览器、7 接收时间戳。

​

标题

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

• 网页推送和华为必需
• 未设置时在网页上默认为网站名称
• 建议限制：25–50 个字符（移动端），60–80 个字符（网页）
• 支持：AI 消息编写器、表情符号、消息个性化、多语言消息
• API：headings

​

副标题

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

• 建议限制：25–50 个字符
• 支持：表情符号、消息个性化、多语言消息
• API：subtitle

​

消息

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

• 除非发送后台通知，否则为必需
• 支持：AI 消息编写器、表情符号、消息个性化、多语言消息
• 建议限制：约 150 个字符
• API：contents

​

图标

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

• 参见通知图标

​

图片

在 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 网页）
• 参见图片和富媒体

​

应用名称

显示通知的应用名称。

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

​

功能属性

​

操作按钮

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

• 支持 Android 4.1+ 和 iOS 8.0+
• 参见操作按钮

​

启动 URL

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

• API：url（单个通用 URL）、app_url（深度链接，例如 your-app://screen）、web_url（http/https 网页链接）
• 参见 URL、链接和深度链接

​

徽章

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

• iOS：红色数字徽章；可设置、增加或清除。API：ios_badgeType、ios_badgeCount
• Android：需要通知类别
• 华为：徽章显示为数字或圆点。API：huawei_badge_class、huawei_badge_set_num、huawei_badge_add_num
• Web（Android 版 Chrome）：Android 设备上 Chrome 网页通知的单色状态栏图标。这不是应用图标徽章。建议：正方形 PNG，96×96（最小 72×72）。API：chrome_web_badge。参见通知图标
• 参见徽章

​

声音

推送送达时播放声音。

• iOS：使用 ios_sound 设置
• Android：通过通知类别设置
• 网页：不可用

​

附加数据

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

• 适用于移动服务扩展以及移动 SDK 和网页 SDK 中的点击监听器
• 仪表板仅支持简单的键值数据；发送嵌套 JSON 请使用带有 data 的 API
• 最大总载荷：约 4 KB；data 字段：最多 2048 字节
• 参见通知载荷参考

​

Collapse ID（移动推送）

如果共享相同的 collapse_id，则用更新的通知替换早期通知。最大长度：64 个字符。API：collapse_id 例如，天气应用发送三条预警。如果用户在三条全部发送后才打开设备，则只显示最后一条消息。

​

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

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

​

优先级

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

• 高（10，默认且推荐）：即时、基于警报的消息。
• 普通（5）：建议用于后台和纯数据通知。
• API：priority
• 平台文档：APNs 优先级、FCM 优先级

​

存活时间（TTL）

设备离线时消息的保留时长。默认：3 天。范围：0–2,419,200 秒（28 天）。API：ttl 如果用户离线且 TTL 过期，消息将被丢弃。对于绝不应延迟送达的消息，请设置 ttl: 0。

​

通知分组

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

• iOS：在 API 中使用 thread_id 将消息归入同一组。
• Android：在 API 中使用 android_group，或在仪表板中设置”组键”。如需高级自定义，参见 Android 通知服务扩展和 Android 分组通知指南。

​

华为消息类型（华为）

控制 OneSignal 如何向华为（HMS）设备投递推送。API：huawei_msg_type

• data：OneSignal SDK 在客户端渲染通知，可启用完整功能集（大图片、操作按钮）和确认送达。如果应用被强制退出，则不会显示。
• message（默认）：由 HMS Core 在服务端渲染；仅标题和正文，但即使应用被强制退出也会显示。
• 参见 huawei_msg_type 和数据和后台通知。

---

​

取消推送通知

如果消息尚未送达，可以取消它。OneSignal 将停止向所有尚未加入队列的订阅发送消息。这不会从已收到消息的设备上删除消息。 在消息报告中，选择操作 > 取消，或使用取消消息 API。

​

从设备移除推送通知

消息送达后，仅在设置了 Collapse ID 或网页推送主题 的情况下，才能替换推送通知。未设置这两项时，通知无法被替换或移除。

---

​

分析

跟踪消息性能和参与度。

---

​

常见问题

​

OneSignal 推送支持哪些平台？

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

​

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

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

​

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

常见原因包括平台凭据缺失或过期、用户未授予权限，或设备级别的设置（如勿扰模式）。完整的故障排除清单请参见通知未显示或延迟。

​

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

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