社交活动

当发生与用户相关的事件时通知他们：点赞、回复、关注、收到的消息或游戏中的竞技事件。即使用户当前没有在您的应用中活跃，这些通知也能推动重新参与。

OneSignal 并非为实时通信而设计。推送通知最适合在用户没有活跃在应用中时用作备用方案。对于实时应用内消息，请使用应用现有的消息层，仅当接收者离线或不活跃时才触发 OneSignal 通知。

当有人点赞、评论、提及、标记或关注用户时通知他们。

私信

通过防抖和会话深度链接提醒用户有新的收到的消息。

游戏提醒

发送具有时效性的竞技事件，如基地被攻击、挑战和公会活动。

前提条件

在开始之前，请确保您已具备：

已在您的应用中安装 OneSignal SDK。参见移动 SDK 设置或 Web SDK 设置。
为每个用户设置了 external_id，以便您可以通过自己的标识符定向他们。参见用户与别名。
一个可以检测社交操作并调用 OneSignal API 的后端。参见 REST API 概览。
如果您计划使用 custom_data 进行个性化，需在仪表板中创建模板。使用 custom_data 必须提供 template_id。

保持 custom_data 载荷在 2KB 以内。 custom_data 字段有硬性大小限制。发送大型载荷——完整会话列表、排行榜数组、base64 图片或 HTML——有被截断或拒绝的风险。对于丰富内容，请传递一个标识符（例如 digest_id 或 summary_url），并让接收者的设备在点击时从您的后端获取完整载荷。有关大小限制详情和数组迭代模式，请参见使用 API custom_data 个性化消息。

社交活动通知

当用户参与社交操作时发送推送通知。使用 custom_data 在发送时将发送者的姓名、头像和相关上下文注入消息中。不会有任何数据存储在 OneSignal 中。

常见社交操作

操作	示例通知
点赞	”Anna 点赞了你的照片。“
评论	”Leo 回复：“看起来太棒了！""
提及	”Sara 在评论中提及了你。“
标记	”James 在帖子中标记了你。“
关注	”Maya 开始关注你。“
邀请	”Ben 邀请你参加活动。“
分享	”Alex 与你分享了’夏威夷相册’。“

设置

在您的后端检测操作

当发生社交操作时，您的后端识别发送者和接收者，以及帖子 ID 或内容等任何相关上下文：

JSON

{
  "action": "like",
  "sender_id": "user_b",
  "sender_name": "Anna",
  "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
  "recipient_id": "user_a",
  "post_id": "xyz789",
  "post_title": "My Hawaii trip"
}

创建推送模板

在仪表板中，前往 Messages > Templates > New Push Template。使用 Liquid 语法引用 custom_data 字段：标题：

Liquid

{{ message.custom_data.sender_name | default: "Someone" }}

消息：

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} liked your post "{{ message.custom_data.post_title | default: "your post" }}".

图片（可选，显示发送者的头像）：

Liquid

{{ message.custom_data.sender_avatar }}

保存模板并记下它的 template_id。

调用 Create Message API

从您的后端向接收者发送通知：

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
    "post_title": "My Hawaii trip",
    "post_id": "xyz789"
  },
  "url": "yourapp://posts/xyz789"
}

OneSignal 在发送时使用 custom_data 的值渲染模板。发送者的姓名和头像会出现在通知中，但不会存储在 OneSignal 中。

可选：添加邮件和短信备用方案

要触达已禁用推送或通知未送达的用户，请参见下方的邮件和短信备用方案。

在每个 Liquid 占位符中使用 | default: 过滤器，这样即使某个字段缺失，消息仍能自然通顺。例如：{{ message.custom_data.sender_name | default: "Someone" }}。更多过滤器请参见使用 Liquid 语法。

头像和图片 URL 要求。 sender_avatar URL（以及任何其他通知图片）必须：

HTTPS — iOS 会拒绝 HTTP URL。
可公开访问 — APNs 和 FCM 无法发送需要身份验证的请求。
小于约 1 MB — iOS 上限为 10 MB，但实际投递窗口更适合较小的资源。
以正确的 Content-Type 标头提供 — image/jpeg、image/png 等。

通过带缓存标头的 CDN 托管是最安全的设置。

限制高频操作

一个爆火的帖子每秒可能产生数千个 like 事件。不要为每个事件都发送推送——那会淹没接收者，并导致您的应用被静音或卸载。正确的模式是：

在您的后端累积计数（例如，以接收者 + 帖子为键的 Redis 计数器）。
在一段静默窗口后（10 分钟是合理的默认值），发送一条汇总推送：“12 人点赞了你的帖子。”
如果汇总后又有新的点赞到来，开始一个新的窗口——不要立即再次推送。

同样的逻辑适用于评论、关注和互动反应。如果您的后端无法防抖，请参见限流了解 OneSignal 侧的速率限制。

直接（用户对用户）消息

当用户收到新私信时通知他们，并通过深度链接直接带他们进入会话。

仅当接收者没有活跃在聊天中时才发送推送。通知一个正在阅读该会话的人会造成糟糕的体验。请使用您应用自己的逻辑，在触发通知前检查接收者当前是否活跃。OneSignal 不会跟踪用户当前是否正在使用您的应用。

设置

检测消息发送并检查活跃状态

当用户 A 向用户 B 发送消息时，检查用户 B 当前是否活跃在该会话中。如果用户 B 离线或不在会话中，则继续发送推送。

避免为每条消息发送一条推送

如果用户 A 连续发送了多条消息，请在最后一条消息之后等待一小段时间再触发通知。以下是在您的后端实现的方法：

当第一条消息到达时，启动一个计时器（例如 60 秒）。
如果在计时器结束前又有消息到达，则重置计时器。
当计时器结束且没有新消息时，发送一条汇总未读数量的推送。

OneSignal 不会自动合并多次 API 调用，因此如果您调用 API 五次，就会发送五条通知。

发送推送通知

向用户 B 发送带有会话深度链接的推送：

JSON

{
  "app_id": "YOUR_APP_ID",
  "headings": { "en": "New message" },
  "contents": { "en": "Anna: 'Hey, you around?'" },
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "url": "yourapp://chat/chat_1234",
  "data": {
    "click_action": "open_chat",
    "conversation_id": "chat_1234",
    "sender_id": "user_a_id"
  }
}

您的应用在通知打开时读取 data.conversation_id 并导航到正确的屏幕。有关各平台的设置，请参见深度链接。

可选：添加邮件和短信备用方案

要触达已禁用推送或通知未送达的用户，请参见下方的邮件和短信备用方案。

在系统层面按会话分组通知。 后端防抖可以减少触发的通知数量，但 iOS 和 Android 还可以在视觉上将多条通知折叠成一个线程。设置线程或折叠标识符（例如 conversation_id），让操作系统将来自同一聊天的消息分组。参见通知分组。

每收到新消息时更新徽章数字。 大多数聊天应用希望 iOS/Android 徽章反映所有会话中的未读消息总数。每次推送时通过 API 传递未读数量，这样即使用户清除了一条通知但还有其他未读通知，徽章也能保持准确。参见徽章。

锁屏隐私。 iOS 默认在锁屏上显示通知内容——包括消息预览（“Anna: ‘Hey, you around?’”）。对于包含敏感内容的消息应用（健康、金融、约会、职场），请考虑发送通用预览（“来自 Anna 的新消息”），并让用户通过您的应用内设置选择开启完整预览。

游戏：竞技和社交提醒

竞技类游戏受益于能制造紧迫感的时效性提醒。使用 custom_data 让这些通知显得具体且个人化。一条指名攻击者或显示确切资源数量的通知远比通用提醒更有吸引力。

常见竞技事件

事件	示例通知
基地被攻击	”你的村庄正遭受攻击！Orca 正在袭击你的基地。“
挑战	”DragonSlayer99 向你发起了排位决斗挑战。你有 24 小时时间回应。“
排行榜	”你已跌出前 10 名。Orca 刚刚在第 8 名超越了你。“
公会事件	”公会战 30 分钟后开始。BladeClan 就指望你了！“
战队邀请	”DragonSlayer99 邀请你加入 BladeClan。“
资源就绪	”你的部队已训练完毕，随时可以部署。“

设置

在您的后端检测游戏事件

当竞技事件发生时，您的游戏后端识别受影响的玩家并捕获相关上下文：

JSON

{
  "event": "base_attack",
  "attacker_id": "user_orca",
  "attacker_name": "Orca",
  "recipient_id": "user_dragon",
  "resources_at_risk": {
    "gold": 12400,
    "elixir": 8200
  }
}

创建推送模板

在仪表板中，创建带有 Liquid 引用的推送模板：标题：

Liquid

⚔️ Your village is under attack!

消息：

Liquid

{{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. You're at risk of losing {{ message.custom_data.gold | default: "0" }} gold and {{ message.custom_data.elixir | default: "0" }} elixir.

保存模板并记下它的 template_id。

发送通知

从您的游戏后端调用 Create Message API：

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "attacker_name": "Orca",
    "gold": "12400",
    "elixir": "8200"
  },
  "url": "yourgame://base/defend",
  "data": {
    "event": "base_attack",
    "attacker_id": "user_orca"
  }
}

url 通过深度链接将玩家直接带到防御屏幕。data 对象将上下文传递给您应用的通知处理程序，以便加载正确的战斗状态。

可选：添加邮件和短信备用方案

要触达已禁用推送或通知未送达的玩家，请参见下方的邮件和短信备用方案。

对非紧急提醒遵守免打扰时段。 在当地时间凌晨 3 点发送基地被攻击的推送是众所周知的退订诱因。请将您的游戏提醒分为两个层级：

时间紧迫型（公会战 30 分钟后开始、基地此刻正遭受攻击）——无论当地时间如何都立即发送。
非时间紧迫型（部队已就绪、每日奖励可领取、每周回顾）——使用智能投递或按时区自定义时间，让它们在玩家当地时区的清醒时段送达。

大多数游戏提醒的退订来自第二类在错误时间发送，而不是第一类过于频繁。

考虑为进行中的事件使用 Live Activities。 对于 iOS 16.1+ 上正在进行的对局、副本或直播事件，锁屏和灵动岛上的 Live Activity 通常比针对同一上下文反复更新的推送通知体验更好。将 Live Activities 用于实时状态（“剩余 23 分钟，你排名第 4”），把推送留给里程碑或完成时刻。

邮件和短信备用方案

为任何通知类型添加邮件或短信备用方案，以触达已禁用推送或通知未送达的用户。使用 View Message API 检查是否有确认送达或点击记录。如果在您的延迟窗口内没有记录，则使用相同的 custom_data 方法通过邮件或短信模板发送后续消息。

社交活动最适合提及和直接回复等高价值操作。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
    "action": "liked your post",
    "post_title": "My Hawaii trip",
    "post_url": "https://yourapp.com/posts/xyz789"
  }
}

邮件模板示例（主题）：

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} {{ message.custom_data.action | default: "interacted with your post" }}

私信最适合作为未读会话的每日汇总，而不是按条消息提醒。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "custom_data": {
    "unread_count": "3",
    "conversations": [
      { "sender_name": "Anna", "preview": "Hey, you around?", "url": "https://yourapp.com/chat/chat_1234" },
      { "sender_name": "Leo", "preview": "Did you see this?", "url": "https://yourapp.com/chat/chat_5678" }
    ]
  }
}

邮件模板示例（主题）：

Liquid

You have {{ message.custom_data.unread_count | default: "new" }} unread message{% if message.custom_data.unread_count != "1" %}s{% endif %}

邮件模板示例（正文，迭代 conversations 数组）：

Liquid

<h2>You have {{ message.custom_data.unread_count }} unread messages</h2>
<ul>
  {% for conversation in message.custom_data.conversations %}
    <li>
      <strong>{{ conversation.sender_name }}:</strong>
      "{{ conversation.preview }}"
      <a href="{{ conversation.url }}">Open</a>
    </li>
  {% endfor %}
</ul>

有关完整的数组迭代参考，包括嵌套对象和条件渲染，请参见使用 API custom_data 个性化消息。游戏最适合非紧急回顾，如每周排行榜总结、公会战结果或里程碑解锁。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "player_name": "DragonSlayer99",
    "rank": "7",
    "rank_change": "+3",
    "top_players": [
      { "name": "Orca", "score": "48200" },
      { "name": "Shadow", "score": "45100" },
      { "name": "DragonSlayer99", "score": "43800" }
    ],
    "summary_url": "https://yourgame.com/rankings/weekly"
  }
}

邮件模板示例（主题）：

Liquid

Your weekly rankings: #{{ message.custom_data.rank }} ({{ message.custom_data.rank_change }} this week)

社交活动最适合提及和直接回复等高重要性操作，而不是日常的点赞或关注。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "post_title": "My Hawaii trip",
    "post_url": "https://yourapp.com/posts/xyz789"
  }
}

短信模板示例：

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} mentioned you in "{{ message.custom_data.post_title | default: "a post" }}". Tap to reply: {{ message.custom_data.post_url }}

私信最适合单条错过的消息，而不是批量消息序列。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "message_preview": "Hey, you around?",
    "conversation_url": "https://yourapp.com/chat/chat_1234"
  }
}

短信模板示例：

Liquid

New message from {{ message.custom_data.sender_name | default: "a user" }}: "{{ message.custom_data.message_preview }}". Reply in the app: {{ message.custom_data.conversation_url }}

游戏最适合基地被攻击等玩家需要立即行动的时间紧迫事件。

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "attacker_name": "Orca",
    "gold": "12400",
    "game_url": "https://yourgame.com/base/defend"
  }
}

短信模板示例：

Liquid

⚔️ ATTACK! {{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. {{ message.custom_data.gold | default: "0" }} gold at risk. Defend now: {{ message.custom_data.game_url }}

让用户控制自己的备用方案偏好。类似”如果我错过消息，请通过短信通知我”的选择加入，有助于避免向有意禁用推送的用户发送不想要的消息。

常见问题

OneSignal 能像聊天应用一样实时发送通知吗？

不能。推送通知通过 Apple（APNs）和 Google（FCM）的基础设施投递，投递时间不固定且没有送达保证。请使用应用现有的消息层进行实时应用内通信，并在接收者没有活跃在应用中时将 OneSignal 用作备用方案。

如何避免通知已经在应用中的用户？

OneSignal 不会跟踪用户当前是否活跃在您的应用中。您自己的后端逻辑必须决定是否触发通知。只有在确认接收者离线或不在相关屏幕上时才调用 OneSignal API。

如何防止连续快速发送的消息产生多条通知？

在您的后端发送通知前添加一个短暂延迟。当第一条消息到达时，启动一个计时器。如果在计时器结束前又有消息进来，则重置它。当计时器结束时，发送一条包含未读数量的推送。OneSignal 不会自动合并多次 API 调用，因此如果您调用 API 五次，就会发送五条通知。

消息发送后 `custom_data` 会保存到用户的资料中吗？

不会。custom_data 是临时的，仅在 API 请求期间存在，用于在发送时渲染模板。它不会存储在 OneSignal 中，也无法在未来的消息或 Journeys 中重复使用。对于持久化用户数据，请使用标签。

可以在一次 API 调用中定向多个接收者吗？

可以。在 include_aliases 数组中传递多个 external_id 值。如果每个接收者需要不同的个性化内容（例如不同的攻击者名称），请使用 custom_data 中的批量个性化模式。完整方法请参见使用 API custom_data 个性化消息。每次调用的确切接收者上限和速率限制记录在 Create Message API 参考中——对于非常大的受众，基于细分的定向比每次调用传递数千个 external_id 值更高效。

我需要为国际用户本地化消息吗？

对于任何跨语言的受众，需要。headings 和 contents 字段接受多个语言代码（例如 { "en": "...", "es": "...", "fr": "..." }），OneSignal 会根据每个订阅的语言选择正确的变体。同样的模式也适用于模板字段。完整参考（包括备用语言行为）请参见多语言消息。

使用 API custom_data 个性化消息

使用 custom_data 和 Liquid 语法将动态的、特定于消息的数据注入模板。

消息个性化

OneSignal 中所有个性化选项的概览，包括标签、用户属性和细分。

深度链接

当用户点击通知时将他们带到应用中的特定屏幕。

创建活动动态

使用 OneSignal 的通知收件箱在您的应用内显示社交提醒历史记录。

模板

为推送、邮件和短信创建和管理可重用的消息模板。

Create Message API

发送消息的完整 API 参考，包括 custom_data、定向和所有可用字段。

教程

🏢 按行业

📈 提高参与度和留存

🔔 交付关键或时间敏感消息

🧠 增强目标定位和个性化

🛠️ 改进用户体验和入职

社交活动

社交活动

私信

游戏提醒

前提条件

社交活动通知

常见社交操作

设置

限制高频操作

直接（用户对用户）消息

设置

游戏：竞技和社交提醒

常见竞技事件

设置

更多游戏提醒示例

邮件和短信备用方案

常见问题

OneSignal 能像聊天应用一样实时发送通知吗？

如何避免通知已经在应用中的用户？

如何防止连续快速发送的消息产生多条通知？

消息发送后 `custom_data` 会保存到用户的资料中吗？

可以在一次 API 调用中定向多个接收者吗？

我需要为国际用户本地化消息吗？

相关页面

使用 API custom_data 个性化消息

消息个性化

深度链接

创建活动动态

模板

Create Message API

社交活动

私信

游戏提醒

​前提条件

​社交活动通知

​常见社交操作

​设置

​限制高频操作

​直接（用户对用户）消息

​设置

​游戏：竞技和社交提醒

​常见竞技事件

​设置

​更多游戏提醒示例

​邮件和短信备用方案

​常见问题

​OneSignal 能像聊天应用一样实时发送通知吗？

​如何避免通知已经在应用中的用户？

​如何防止连续快速发送的消息产生多条通知？

​消息发送后 custom_data 会保存到用户的资料中吗？

​可以在一次 API 调用中定向多个接收者吗？

​我需要为国际用户本地化消息吗？

​相关页面

使用 API custom_data 个性化消息

消息个性化

深度链接

创建活动动态

模板

Create Message API

前提条件

社交活动通知

常见社交操作

设置

限制高频操作

直接（用户对用户）消息

设置

游戏：竞技和社交提醒

常见竞技事件

设置

更多游戏提醒示例

邮件和短信备用方案

常见问题

OneSignal 能像聊天应用一样实时发送通知吗？

如何避免通知已经在应用中的用户？

如何防止连续快速发送的消息产生多条通知？

消息发送后 `custom_data` 会保存到用户的资料中吗？

可以在一次 API 调用中定向多个接收者吗？

我需要为国际用户本地化消息吗？

相关页面