> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 自定义事件
> 使用自定义事件跟踪用户行为，用于触发旅程、通过等待直到步骤控制流程，以及实时个性化消息。
## 什么是自定义事件？
自定义事件是您发送给 OneSignal 的命名用户操作（或无操作）。您可以从应用、网站或外部系统发送事件，以便触发自动化、控制旅程流程，并实时个性化用户体验。
**示例包括：**
* 完成新手引导
* 进行购买
* 放弃购物车
* 取消订阅
* 达到新游戏等级
**当 OneSignal 收到自定义事件时，您可以：**
* 启动旅程
* 通过等待直到步骤继续旅程
* 让用户退出旅程
* 使用事件属性个性化消息
* 按行为细分用户（早期访问）
### 何时应该使用自定义事件？
在以下情况下使用自定义事件：
* 消息传递需要响应实时用户行为
* 数据代表已发生的事情（而非永久状态）
* 您需要事件属性用于个性化或旅程逻辑
在以下情况下不要使用自定义事件：
* 您想存储长期用户属性（请改用标签）
自定义事件代表在特定时间点发生的事情。与标签不同，它们不会永久更新用户的资料——它们记录的是行为。
请参阅下方的[标签 vs 自定义事件](#标签-vs-自定义事件)了解详细对比。
### 自定义事件结构
自定义事件包含以下字段：
事件名称。最大 `128` 个字符。
描述事件的可选参数（例如：计划名称、产品 ID 或价格）。这些参数可用于个性化和旅程流程控制。
用户的外部 ID。使用[创建自定义事件 API](/reference/create-custom-events) 时需要用户标识符。必须提供 `external_id` 或 `onesignal_id` 之一。
事件发生（或将要发生）的时间，格式为 ISO 8601 字符串。请参阅[创建自定义事件 API](/reference/create-custom-events)。
用于防止重复事件处理的唯一 UUID。请参阅[创建自定义事件 API](/reference/create-custom-events)。
事件大小限制：
* 最大事件负载：2024 字节
* 最大请求大小（多个事件）：1 MB
***
## 将自定义事件发送到 OneSignal
无论来源如何，所有事件在计费方面均同等对待。
### API 和 SDK
从您的后端发送事件。
在客户端追踪事件。
自定义事件负载示例：
```json JSON theme={null}
{
"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"
}
]
}
```
### 集成
OneSignal 连接到 25 个以上的外部数据源来导入自定义事件——包括数据仓库、数据库和流式平台——无需自定义代码。
在 Segment 和 OneSignal 之间路由事件和受众。
同步群体并从 Amplitude 导入自定义事件。
同步群体并从 Mixpanel 导入自定义事件。
从您的 Snowflake 数据仓库导入自定义事件。
从 BigQuery 数据集导入自定义事件。
从 Kafka 主题流式传输自定义事件。
查看将自定义事件导入 OneSignal 的数据库、数据仓库和流式平台的完整列表。
**没有开发者资源？** 直接从 [Google Sheets](./google-sheets) 电子表格导入自定义事件——无需代码。将事件数据添加到表格中，OneSignal 会自动导入。适合早期实验或没有工程支持的团队。
### 验证事件已接收
发送事件后，在 **Data > Custom Events** 中确认它们已到达 OneSignal。
#### 事件列表标签页
事件列表标签页提供应用中所有自定义事件的概览，按事件名称组织。
对于每种事件类型，您可以查看：
* 已摄取的事件总数
* 最近的事件（包含完整 JSON 负载和属性）
* 事件来源（SDK、API 或集成）
* 最后发生的时间戳
选择一个事件以打开其详细视图，您还可以在其中更新保留期。
详细视图包括：
* **来源细分**：按来源摄取的事件数量。展开可查看最新的事件架构和最近事件的时间戳。
* **活动**：最近 10 个事件，包括来源和时间戳。展开任意条目可检查完整的 JSON 负载。
* **使用情况**：事件当前的使用位置（旅程或细分）。点击可直接进入关联的旅程或细分以修改其设置。
#### 事件活动标签页
事件活动标签页提供已摄取到您的 OneSignal 应用中的最新事件的实时动态。
使用它来：
* 按事件名称、来源或外部 ID 过滤
* 检查完整的 JSON 负载
* 调试集成问题
动态不会自动刷新。发送新事件后请手动刷新。
***
## 在 OneSignal 中使用自定义事件
事件开始流入 OneSignal 后，您可以通过以下方式使用它们：
### 触发旅程进入和退出规则
将自定义事件设置为旅程的进入或退出规则，以便在事件发生时立即添加或移除用户。
示例：
* `signup_completed` → 开始新手引导或将用户从试用鼓励旅程中移除
* `purchase` → 发送确认和交叉销售，或将用户从放弃购物车旅程中移除
使用自定义事件将用户添加到旅程。
### 控制旅程流程（等待直到）
使用等待直到步骤暂停用户，直到自定义事件发生。
示例：
* 在 `added_to_cart` 之后等待 `purchase`
您可以定义过期时间窗口。如果用户未能及时触发事件，您可以发送后备消息或退出旅程。
暂停用户直到自定义事件发生。
### 使用事件属性个性化旅程
在旅程模板中使用 Liquid 引用事件属性。
示例：
```liquid Liquid theme={null}
Thanks for purchasing {{ journey.first_event.properties.item }}!
```
使用事件属性个性化旅程的完整指南。
### 使用自定义事件细分用户
根据自定义事件的发生创建细分。
自定义事件细分目前处于早期访问阶段。
要申请访问权限，请发送电子邮件至 `support@onesignal.com`，并提供：
* 您的公司名称
* 您的 OneSignal App ID
当前限制：
* 不支持与电子邮件预热或 A/B 测试一起使用
* 无法驱动旅程
* 无法与其他细分过滤器组合使用
细分完整指南。
***
## 计划可用性和保留成本
自定义事件在所有付费计划上可用。
了解事件保留和定价。
***
## 标签 vs 自定义事件
[标签](/docs/en/add-user-data-tags)和[自定义事件](/docs/en/custom-events)都是向用户添加数据的方式。但是，它们之间存在一些关键区别：
| 功能 | 标签 | 自定义事件 |
| ------- | :-----------------------: | :----------------------------------------------------: |
| 数据用途 | 细分和个性化 | 无需细分即可触发旅程、等待步骤、直接在旅程中实现个性化 |
| 数据 保留期限 | 永久 | 30天以上（[提供永久存储](/docs/en/billing-faq#streaming-events)） |
| 数据格式 | 键值对字符串或数字 | JSON |
| 数据来源 | OneSignal SDK、API 或集成（有限） | OneSignal SDK、API 或集成 |
| 数据访问 | 细分和消息个性化 | 旅程和旅程消息模板个性化、细分（即将推出） |
标签和自定义事件之间的关键区别在于它们的深度和使用场景。标签是用户的属性，例如姓名、账户状态或位置。事件是用户已完成的操作，例如购买商品、完成关卡或邀请好友。标签和事件都可用于细分和个性化。
在实际应用中，您可能会同时使用两者：
* 标签用于静态且不经常更改的用户属性
* 自定义事件用于实时场景、复杂细分和更复杂的旅程工作流
***