跳转到主要内容

​
概览

自定义事件让您能够跟踪来自应用、网站或外部系统的有意义用户操作——并实时对其做出反应。发送OneSignal之外发生的行为用户事件，并使用它们提供更有针对性、相关性和时效性的消息传递。 您可以：
  • 使用OneSignal SDK直接从应用或网站发送事件
  • 从集成、CDP或数据仓库导入事件
  • 使用它们触发旅程、激活等待直到步骤，并根据实时行为细分用户（细分选项即将推出）
示例用例：
  • 用户注册 → 开始入门旅程
  • 用户放弃结账 → 发送提醒或优惠
  • 玩家达到新级别 → 发送应用内奖励
  • 用户尝试取消账户 → 触发挽回活动

​
什么是自定义事件？

自定义事件是任何对您的业务重要的被跟踪用户操作——或无操作。常见示例包括：
  • 进行购买
  • 完成游戏关卡
  • 开始锻炼
  • 取消订阅
每个事件都可以包含属性来提供额外的上下文。 自定义事件结构：
  • name（字符串，必需）— 事件名称，最大128个字符
  • properties（对象，可选）— JSON格式的上下文数据
  • 用户标识符（必需）— 要么是external_id要么是onesignal_id
示例： 
{
  "events": [
    {
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "name": "purchase",
      "properties": {
        "item": "T恤",
        "size": "小号",
        "color": "蓝色",
        "price": 24.99
      }
    }
  ]
}
自定义事件可以：
  • 从您的应用或站点实时产生（OneSignal移动/Web SDK）
  • 从Segment、Amplitude或Databricks等集成摄取（即将推出）
  • 从您的仓库或CDP导入（即将推出）

​
标签 vs 自定义事件

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

​
将自定义事件导入OneSignal

您可以使用我们的API直接生成事件或从其他系统摄取它们。
所有事件——无论是从SDK生成还是从数据仓库摄取——在计费方面都受到相同对待。

​
OneSignal API和SDK

通过以下方式发送事件： 示例：通过API发送
curl
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    {
      "name": "completed_onboarding",
      "external_id": "user_12345",
      "properties": {
        "plan": "专业版",
        "time_to_complete": 600
      }
    }
  ]
}'
​
name
string
required
事件的标识符或名称。最大128个字符。
​
external_id
string
事件目标用户的外部ID。需要用户的外部ID或OneSignal ID之一。
​
properties
object
关于事件的可选参数（例如，计划名称、产品ID、价格）。
此事件将立即将external_id为user_12345的用户添加到以completed_onboarding作为自定义事件入口规则触发器或等待直到操作的旅程中。

​
集成

如果事件已在其他地方跟踪，请通过支持的集成导入它们。

​
查看和验证事件

事件开始流入后，您可以通过OneSignal中的几个工具查看和排除故障。

​
事件列表标签

导航到您的组织

事件列表标签提供您的事件的高级仪表板，按事件类型组织。对于每种事件类型，您可以看到摄取的事件总数、最近摄取的事件（以JSON格式显示其属性）、事件源（SDK、API或集成）以及事件类型最后发生的时间。在每个事件的详细视图中，您还可以选择更新其保留期。 子详细视图在三个关键领域提供额外的洞察：
  • 源细分 – 显示按源摄取的事件数量，可以选择展开并查看事件的最新架构以及最后看到事件的时间戳。
  • 活动 – 列出最近摄取的10个事件，显示其源和时间戳。每个条目都可以展开以显示事件的完整JSON有效负载。
  • 使用情况 – 显示特定事件在OneSignal中的使用位置，例如在细分或旅程中。从这里，您可以直接点击相关的细分或旅程以访问其设置。

​
事件活动标签

导航到您的组织

事件活动标签提供摄取到您的OneSignal应用的最新事件的实时动态。您可以展开动态以查看最多90天前的事件，并按源、事件属性或外部ID应用过滤器。此标签在配置事件源时调试问题特别有用，因为它允许您验证事件是否按预期到达您的应用程序。请注意，动态不会自动刷新，因此您需要在发送新事件后手动刷新它以查看最新活动。

​
事件存储标签 （即将推出）

用于管理您的OneSignal应用程序的事件存储的专用视图。

​
在OneSignal中使用自定义事件

​
使用事件触发旅程

事件触发旅程让您基于实时活动立即向用户发送消息——无需等待细分更新。您可以在用户执行关键操作的瞬间开始旅程。

​
等待直到事件

使用等待直到步骤在旅程中暂停用户，直到发生特定自定义事件或其他操作。
您还可以定义过期时间窗口。如果用户没有及时满足条件，您可以继续沿着后备路径，发送替代消息，或退出旅程。

​
通过自定义事件进行细分

使用自定义事件进行细分目前处于早期访问阶段。 要申请访问权限，请联系support@onesignal.com并提供：
  • 您的公司名称
  • 您想要启用的OneSignal App ID(s)
您可以根据自定义事件的发生创建细分。这将使您能够使用OneSignal SDK根据应用程序上的行为或从OneSignal外部捕获的事件来细分用户。有关自定义事件细分的更多详细信息，请参阅细分页面。 该功能在早期访问期间的限制：
  • 不能与电子邮件预热和A/B测试一起使用。
  • 自定义事件细分不能用于驱动旅程。
  • 您还不能将自定义事件过滤器与其他细分过滤器（如用户属性或消息事件）结合使用。

​
计划可用性和保留成本

自定义事件在所有付费计划上可用。请参阅计费FAQ了解更多详细信息。