跳转到主要内容

​
什么是自定义事件？

自定义事件是您发送给 OneSignal 的命名用户操作（或无操作）。您可以从应用、网站或外部系统发送事件，以便触发自动化、控制旅程流程，并实时个性化用户体验。 示例包括：
  • 完成新手引导
  • 进行购买
  • 放弃购物车
  • 取消订阅
  • 达到新游戏等级
当 OneSignal 收到自定义事件时，您可以：
  • 启动旅程
  • 通过等待直到步骤继续旅程
  • 让用户退出旅程
  • 使用事件属性个性化消息
  • 按行为细分用户（早期访问）

​
何时应该使用自定义事件？

在以下情况下使用自定义事件：
  • 消息传递需要响应实时用户行为
  • 数据代表已发生的事情（而非永久状态）
  • 您需要事件属性用于个性化或旅程逻辑
在以下情况下不要使用自定义事件：
  • 您想存储长期用户属性（请改用标签）
自定义事件代表在特定时间点发生的事情。与标签不同，它们不会永久更新用户的资料——它们记录的是行为。请参阅下方的标签 vs 自定义事件了解详细对比。

​
自定义事件结构

自定义事件包含以下字段：
​
name
string
必填
事件名称。最大 128 个字符。
​
properties
object
描述事件的可选参数（例如：计划名称、产品 ID 或价格）。这些参数可用于个性化和旅程流程控制。
​
external_id
string
用户的外部 ID。使用创建自定义事件 API 时需要用户标识符。必须提供 external_id 或 onesignal_id 之一。
​
timestamp
string
事件发生（或将要发生）的时间，格式为 ISO 8601 字符串。请参阅创建自定义事件 API。
​
idempotency_key
string
用于防止重复事件处理的唯一 UUID。请参阅创建自定义事件 API。
事件大小限制：
  • 最大事件负载：2024 字节
  • 最大请求大小（多个事件）：1 MB

​
将自定义事件发送到 OneSignal

使用以下方式发送自定义事件：
无论来源如何，所有事件在计费方面均同等对待。
自定义事件负载示例：
JSON
{
  "events": [
    {
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "idempotency_key": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

​
验证事件已接收

发送事件后，在 Data > Custom Events 中确认它们已到达 OneSignal。

​
事件列表标签页

事件列表标签页提供应用中所有自定义事件的概览，按事件名称组织。 对于每种事件类型，您可以查看：
  • 已摄取的事件总数
  • 最近的事件（包含完整 JSON 负载和属性）
  • 事件来源（SDK、API 或集成）
  • 最后发生的时间戳
选择一个事件以打开其详细视图，您还可以在其中更新保留期。 详细视图包括：
  • 来源细分：按来源摄取的事件数量。展开可查看最新的事件架构和最近事件的时间戳。
  • 活动：最近 10 个事件，包括来源和时间戳。展开任意条目可检查完整的 JSON 负载。
  • 使用情况：事件当前的使用位置（旅程或细分）。点击可直接进入关联的旅程或细分以修改其设置。

​
事件活动标签页

事件活动标签页提供已摄取到您的 OneSignal 应用中的最新事件的实时动态。 使用它来：
  • 按事件名称、来源或外部 ID 过滤
  • 检查完整的 JSON 负载
  • 调试集成问题
动态不会自动刷新。发送新事件后请手动刷新。

​
在 OneSignal 中使用自定义事件

事件开始流入 OneSignal 后，您可以通过以下方式使用它们：

​
触发旅程进入和退出规则

将自定义事件设置为旅程的进入或退出规则，以便在事件发生时立即添加或移除用户。 示例：
  • signup_completed → 开始新手引导或将用户从试用鼓励旅程中移除
  • purchase → 发送确认和交叉销售，或将用户从放弃购物车旅程中移除

旅程设置

使用自定义事件将用户添加到旅程。

​
控制旅程流程（等待直到）

使用等待直到步骤暂停用户，直到自定义事件发生。 示例：
  • 在 added_to_cart 之后等待 purchase
您可以定义过期时间窗口。如果用户未能及时触发事件，您可以发送后备消息或退出旅程。

旅程等待直到步骤

暂停用户直到自定义事件发生。

​
使用事件属性个性化旅程

在旅程模板中使用 Liquid 引用事件属性。 示例：
Liquid
Thanks for purchasing {{ journey.first_event.properties.item }}!

自定义事件个性化

使用事件属性个性化旅程的完整指南。

​
使用自定义事件细分用户

根据自定义事件的发生创建细分。
自定义事件细分目前处于早期访问阶段。要申请访问权限，请发送电子邮件至 support@onesignal.com，并提供：
  • 您的公司名称
  • 您的 OneSignal App ID
当前限制：
  • 不支持与电子邮件预热或 A/B 测试一起使用
  • 无法驱动旅程
  • 无法与其他细分过滤器组合使用

细分

细分完整指南。

​
计划可用性和保留成本

自定义事件在所有付费计划上可用。

计费常见问题

了解事件保留和定价。

​
标签 vs 自定义事件

标签和自定义事件都是向用户添加数据的方式。但是，它们之间存在一些关键区别：
功能标签自定义事件
数据用途细分和个性化无需细分即可触发旅程、等待步骤、直接在旅程中实现个性化
数据 保留期限永久30天以上（提供永久存储）
数据格式键值对字符串或数字JSON
数据来源OneSignal SDK、API 或集成（有限）OneSignal SDK、API 或集成
数据访问细分和消息个性化旅程和旅程消息模板个性化、细分（即将推出）
标签和自定义事件之间的关键区别在于它们的深度和使用场景。标签是用户的属性，例如姓名、账户状态或位置。事件是用户已完成的操作，例如购买商品、完成关卡或邀请好友。标签和事件都可用于细分和个性化。 在实际应用中，您可能会同时使用两者：
  • 标签用于静态且不经常更改的用户属性
  • 自定义事件用于实时场景、复杂细分和更复杂的旅程工作流