自定义事件 - OneSignal

什么是自定义事件？

自定义事件是您发送给 OneSignal 的命名用户操作（或无操作）。您可以从应用、网站或外部系统发送事件，以便触发自动化、控制旅程流程，并实时个性化用户体验。 示例包括：

完成新手引导
进行购买
放弃购物车
取消订阅
达到新游戏等级

当 OneSignal 收到自定义事件时，您可以：

启动旅程
通过等待直到步骤继续旅程
让用户退出旅程
使用事件属性个性化消息
衡量转化并将其归因于驱动转化的消息
按行为细分用户（早期访问）

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

在以下情况下使用自定义事件：

消息传递需要响应实时用户行为
数据代表已发生的事情（而非永久状态）
您需要事件属性用于个性化或旅程逻辑

在以下情况下不要使用自定义事件：

您想存储长期用户属性（请改用标签）

自定义事件代表在特定时间点发生的事情。与标签不同，它们不会永久更新用户的资料。它们记录的是行为。请参阅下方的标签 vs 自定义事件了解详细对比。

自定义事件结构

自定义事件包含以下字段：

string

必填

事件名称。最大 512 字节。名称按字节计算，因此由多字节字符组成的名称会比其字符数所显示的更快达到限制。

object

描述事件的可选参数（例如：计划名称、产品 ID 或价格）。这些参数可用于个性化和旅程流程控制。

string

用户的外部 ID。使用创建自定义事件 API 时需要用户标识符。必须提供 external_id 或 onesignal_id 之一。

string

事件发生（或将要发生）的时间，格式为 ISO 8601 字符串。请参阅创建自定义事件 API。

string

用于防止重复事件处理的唯一 UUID。请参阅创建自定义事件 API。

事件大小限制：

最大事件负载：2024 字节
最大请求大小（多个事件）：1 MB

事件名称限制

每个应用最多可以发送 1,000 个唯一的自定义事件名称。使用应用已有名称发送的事件始终会被接受，因此达到限制不会中断您已经在发送的事件。一旦应用达到 1,000 个名称，使用新名称发送的事件将被拒绝。OneSignal 拒绝的是单个事件而不是整个请求，因此同一批次中的其他事件会正常处理。API 返回 HTTP 202 并附带 errors 数组，每个被拒绝的事件都带有错误代码 too many event names。被拒绝的事件不会被存储，不会被计费，也无法触发旅程、个性化消息或用于细分。它会显示在 Data > Events & Conversions 中，标记为失败，原因为 “This app has reached its limit of unique event names”，以便您查看哪些名称被拒绝。要腾出空间，请删除您不再使用的自定义事件名称。删除名称会释放其名额，并永久删除以该名称存储的事件。

当您的应用超过 900 个唯一事件名称时，Custom Events 页面会在任何事件被拒绝之前向您发出警告。

名称限制与 OneSignal 保留每个事件的时长是两回事。有关保留期，请参阅自定义事件存储和保留。

为事件命名以避免达到限制

事件名称说明的是发生了什么。所有会变化的内容都属于属性。将 ID、价格或任何其他可变值放入名称中，会在每次发送时创建一个新的唯一名称，并很快耗尽 1,000 个名称的限制。

{
  "name": "purchase_completed",
  "properties": { "product_id": "SKU-4412", "price": 24.99, "currency": "USD" }
}

{
  "name": "purchase_completed_SKU-4412_24.99"
}

属性可在旅程、转化和细分中使用。

删除事件名称以释放名额

删除自定义事件名称会释放其名额，并永久删除以该名称存储的事件。此操作无法撤消。

查找您不再使用的事件

前往 Data > Events & Conversions 并打开 Event List 标签页。选择一个事件以打开其详细视图。Usage 面板会显示引用该事件的每个旅程和细分，最后发生的时间戳则显示该事件是否仍在到达。

将事件从仍在使用它的任何位置移除

列在 Usage 下的事件是正在使用中的。请先更新或移除这些旅程和细分，否则删除该名称会影响它们的行为。

删除名称

打开事件名称旁边的行菜单并选择 Delete，然后确认。删除自定义事件需要相应权限。如果没有该选项，请联系您账户中拥有授予该权限角色的人员。

刷新页面

删除在后台运行，可能需要几分钟。页面不会自行更新，因此请选择 Refresh List 以确认名称已删除且名额已释放。

将自定义事件发送到 OneSignal

无论来源如何，所有事件在计费方面均同等对待。

API 和 SDK

Create Custom Events API

从您的后端发送事件。

Mobile/Web SDKs

在客户端追踪事件。

自定义事件负载示例：

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"
    },
    {
      "name": "add_to_cart",
      "properties": {
        "item": "Hoodie",
        "size": "medium",
        "color": "black",
        "price": 49.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:12:10.000Z",
      "idempotency_key": "789a0123-b45c-67d8-e901-234567890abc"
    },
    {
      "name": "signup_completed",
      "properties": {
        "plan": "pro",
        "trial": true
      },
      "external_id": "user_67890",
      "timestamp": "2025-10-21T19:15:44.000Z",
      "idempotency_key": "def01234-5678-90ab-cdef-012345678901"
    }
  ]
}

集成

OneSignal 连接到 25 个以上的外部数据源来导入自定义事件，包括数据仓库、数据库和流式平台，无需自定义代码。

Twilio Segment

在 Segment 和 OneSignal 之间路由事件和受众。

Amplitude

同步群体并从 Amplitude 导入自定义事件。

Snowflake

从您的 Snowflake 数据仓库导入自定义事件。

Google BigQuery

从 BigQuery 数据集导入自定义事件。

Apache Kafka

从 Kafka 主题流式传输自定义事件。

浏览所有自定义事件来源

查看将自定义事件导入 OneSignal 的数据库、数据仓库和流式平台的完整列表。

没有开发者资源？ 直接从 Google Sheets 电子表格导入自定义事件，无需代码。将事件数据添加到表格中，OneSignal 会自动导入。适合早期实验或没有工程支持的团队。

验证事件已接收

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

事件列表标签页

事件列表标签页提供应用中所有自定义事件的概览，按事件名称组织。对于每种事件类型，您可以查看：

已摄取的事件总数
最近的事件（包含完整 JSON 负载和属性）
事件来源（SDK、API 或集成）
最后发生的时间戳

选择一个事件以打开其详细视图，您还可以在其中更新保留期。详细视图包括：

来源细分：按来源摄取的事件数量。展开可查看最新的事件架构和最近事件的时间戳。
活动：最近 10 个事件，包括来源和时间戳。展开任意条目可检查完整的 JSON 负载。
使用情况：事件当前的使用位置（旅程或细分）。点击可直接进入关联的旅程或细分以修改其设置。

事件活动标签页

事件活动标签页提供已摄取到您的 OneSignal 应用中的最新事件的实时动态。使用它来：

按事件名称、来源或外部 ID 过滤
检查完整的 JSON 负载
调试集成问题

动态不会自动刷新。发送新事件后请手动刷新。

自定义事件会即时显示在 Custom Events 页面上。但是，事件最多可能需要 5 分钟才会显示在用户资料的 Activity Timeline > Custom Events 下。这是因为 Custom Events 页面反映的是最近的摄取情况，而用户资料由长期存储提供支持。

在 OneSignal 中使用自定义事件

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

触发旅程进入和退出规则

将自定义事件设置为旅程的进入或退出规则，以便在事件发生时立即添加或移除用户。示例：

signup_completed → 开始新手引导或将用户从试用鼓励旅程中移除
purchase → 发送确认和交叉销售，或将用户从放弃购物车旅程中移除

旅程设置

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

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

使用等待直到步骤暂停用户，直到自定义事件发生。示例：

在 added_to_cart 之后等待 purchase

您可以定义过期时间窗口。如果用户未能及时触发事件，您可以发送后备消息或退出旅程。

旅程等待直到步骤

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

使用事件属性个性化旅程

在旅程模板中使用 Liquid 引用事件属性。示例：

Liquid

Thanks for purchasing {{ journey.first_event.properties.item }}!

自定义事件个性化

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

衡量转化

将自定义事件定义为转化指标，以衡量消息传递的业务影响。OneSignal 使用跨渠道最后触达归因模型，将转化归功于驱动转化的推送、电子邮件、短信、应用内和 RCS 消息。在 Settings > Analytics > Conversion Metrics 中进行设置，您可以在此选择事件的衡量方式：

Count（计数）追踪事件发生的频率（例如，15 次购买）。
Value（价值）汇总数值型事件属性（例如，来自 price 属性的 1,250 美元收入）。

转化会显示在全局转化仪表板以及消息、模板和旅程报告中。

事件是否计为转化与其保留期设置无关。即使保留期设置为不存储该事件，该事件仍可计入转化指标。

转化指标

归因窗口、归因模型和设置说明。

使用自定义事件细分用户

根据自定义事件的发生创建细分。

自定义事件细分目前处于早期访问阶段。要申请访问权限，请发送电子邮件至 support@onesignal.com，并提供：

您的公司名称
您的 OneSignal App ID

当前限制：

不支持与电子邮件预热或 A/B 测试一起使用
自定义事件细分基于用户。在旅程（其本身基于用户）之外发送消息时，它们无法与基于订阅的细分组合用于包含或排除。
基于时间的过滤器（“在过去 X 天内发生过”）参考的是 OneSignal 收到事件的时间，而不是事件最初发生的时间。如果您正在导入历史事件并需要按原始事件时间进行细分，请使用标签将事件时间存储为 unix 时间戳。标签过滤器支持”Time Elapsed”运算符，用于动态的基于时间的比较。请注意，标签是用户级别的，因此只会存储最新的值。

细分

细分完整指南。

计划可用性和保留成本

自定义事件在所有付费计划中可用。发送事件是免费的。OneSignal 仅对您存储的事件计费，而存储正是细分和用户资料所需要的。

自定义事件存储和保留

开启存储、为每个事件设置保留期，并管理您已存储的事件。

计费常见问题

事件存储在您的账单上如何显示。

标签 vs 自定义事件

标签和自定义事件都是向用户添加数据的方式。但是，它们之间存在一些关键区别：

功能	标签	自定义事件
数据用途	细分和个性化	无需细分即可触发旅程、等待直到步骤、直接在旅程中实现个性化
数据保留期限	永久	无限（最短 30 天）
数据格式	键值对字符串或数字	JSON
数据来源	OneSignal SDK、API 或 CSV 导入	OneSignal SDK、API 或集成
数据访问	细分和消息个性化	旅程和旅程消息模板个性化、细分（即将推出）

标签和自定义事件之间的关键区别在于它们的深度和使用场景。标签是用户的属性，例如姓名、账户状态或位置。事件是用户已完成的操作，例如购买商品、完成关卡或邀请好友。标签和事件都可用于细分和个性化。在实际应用中，您可能会同时使用两者：

标签用于静态且不经常更改的用户属性
自定义事件用于实时场景、复杂细分和更复杂的旅程工作流

​什么是自定义事件？

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

​自定义事件结构

​事件名称限制

​为事件命名以避免达到限制

​删除事件名称以释放名额

​将自定义事件发送到 OneSignal

​API 和 SDK

Create Custom Events API

Mobile/Web SDKs

​集成

Twilio Segment

Amplitude

Snowflake

Google BigQuery

Apache Kafka

浏览所有自定义事件来源

​验证事件已接收

​事件列表标签页

​事件活动标签页

​在 OneSignal 中使用自定义事件

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

旅程设置

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

旅程等待直到步骤

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

自定义事件个性化

​衡量转化

转化指标

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

细分

​计划可用性和保留成本

自定义事件存储和保留

计费常见问题

​标签 vs 自定义事件

什么是自定义事件？

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

自定义事件结构

事件名称限制

为事件命名以避免达到限制

删除事件名称以释放名额

将自定义事件发送到 OneSignal

API 和 SDK

集成

验证事件已接收

事件列表标签页

事件活动标签页

在 OneSignal 中使用自定义事件

触发旅程进入和退出规则

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

使用事件属性个性化旅程

衡量转化

使用自定义事件细分用户

计划可用性和保留成本

标签 vs 自定义事件