> ## 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.

# Event Stream 数据参考

> Event Streams 和 Webhooks 中可用的所有事件、消息、用户和订阅属性的架构参考，以及每个字段的 Liquid 语法。

使用 [Liquid 语法](./using-liquid-syntax)访问事件流数据。将任意字段包装在 `{{ }}` 中以在事件流正文中包含它。查看[示例](./event-streams#example-body)。

<Warning>
  Journeys 和 API 发送的消息数据保留 30 天。在 30 天后发生的交互事件（点击、打开、取消订阅）可能会有空白的消息属性。要恢复数据，请将交互事件中的 `message.id` 与原始 `sent` 事件关联，该事件包含完整的消息数据。
</Warning>

## `event` 属性

每个事件都包含以下核心字段。`event.data.*` 下的渠道特定字段仅在适用时包含 — 请参见[渠道特定字段](#channel-specific-fields)。

<ParamField body="event.kind" type="string">
  事件类型，结合渠道和操作（例如 `message.push.clicked`、`message.email.bounced`）。请参阅下面[事件类型参考](#event-kind-reference)中的完整值列表。**Liquid：** `{{ event.kind }}`
</ParamField>

<ParamField body="event.id" type="UUID">
  OneSignal 为每个独立事件生成的唯一标识符，采用 UUID v4 格式。使用此 ID 进行幂等投递跟踪。如需消息或模板标识符，请使用 [`message.id`](#message-id) 或 [`message.template_id`](#template-id)。**Liquid：** `{{ event.id }}`
</ParamField>

<ParamField body="event.timestamp" type="integer">
  事件的 UNIX 时间戳。**Liquid：** `{{ event.timestamp }}`
</ParamField>

<ParamField body="event.datetime" type="string">
  事件在 UTC 时间的人类可读时间，格式为 ISO 8601 字符串（例如 "2024-02-21T23:45:15.228Z"）。**Liquid：** `{{ event.datetime }}`
</ParamField>

<ParamField body="event.app_id" type="UUID">
  OneSignal [应用 ID](./keys-and-ids)。**Liquid：** `{{ event.app_id }}`
</ParamField>

<ParamField body="event.subscription_device_type" type="string">
  订阅类型（例如 `iOS`、`Android`、`Chrome`、`Email`、`SMS`）。**Liquid：** `{{ event.subscription_device_type }}`
</ParamField>

<ParamField body="event.subscription_id" type="UUID">
  OneSignal [订阅 ID](./subscriptions)。**Liquid：** `{{ event.subscription_id }}`
</ParamField>

<ParamField body="event.onesignal_id" type="UUID">
  OneSignal [用户 ID](./users)。**Liquid：** `{{ event.onesignal_id }}`
</ParamField>

<ParamField body="event.external_id" type="string">
  您设置为 OneSignal [外部 ID](./users) 别名的用户 ID。如果未设置，可能为空。**Liquid：** `{{ event.external_id }}`
</ParamField>

### 渠道特定字段

这些 `event.data.*` 字段仅存在于某些事件类型中。

#### 应用内消息事件

包含于 `message.iam.*` 事件。详情请参见[应用内消息事件流](./iam-event-streams)。

<ParamField body="event.data.page_name" type="string">
  显示的应用内消息页面或卡片的名称。**Liquid：** `{{ event.data.page_name }}`
</ParamField>

<ParamField body="event.data.page_id" type="string">
  显示的应用内消息页面或卡片的唯一标识符。**Liquid：** `{{ event.data.page_id }}`
</ParamField>

<ParamField body="event.data.target_name" type="string">
  被点击的按钮或图像块元素的名称。该元素必须包含[应用内点击操作](./iam-click-actions)。**Liquid：** `{{ event.data.target_name }}`
</ParamField>

<ParamField body="event.data.target_id" type="string">
  被点击的按钮或图像块元素的唯一标识符。**Liquid：** `{{ event.data.target_id }}`
</ParamField>

#### Live Activity 事件

包含于 `message.live_activity.*` 事件。

<ParamField body="event.data.live_activity_id" type="string">
  特定 Live Activity 的唯一标识符（例如 "Knicks vs Cavs - Oct 22 7PM"）。**Liquid：** `{{ event.data.live_activity_id }}`
</ParamField>

<ParamField body="event.data.live_activity_type" type="string">
  Live Activity 类别的分组标签（例如 "Knicks\_games"）。**Liquid：** `{{ event.data.live_activity_type }}`
</ParamField>

#### 失败事件

包含于 `message.push.failed` 和 `message.email.failed` 事件。

<ParamField body="event.data.failure_reason" type="string">
  消息发送失败的原因。常见原因请参见[推送消息报告](./push-notification-message-reports#failure-message-troubleshooting)或[电子邮件消息报告](./email-message-reports#why-are-my-emails-marked-as-failed)。**Liquid：** `{{ event.data.failure_reason }}`
</ParamField>

### 事件类型参考

每个指标的详细定义，请参见[指标词汇表](./analytics-metrics-glossary)。

| 消息事件类型（OneSignal）          | 事件名称（在数据集中）                          | 事件描述                                                                                                                  |
| -------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Push Sent                  | `message.push.sent`                  | 推送通知成功发送到推送服务（FCM、APNS 等）。                                                                                            |
| Push Received              | `message.push.received`              | 收件人接收到推送通知。并非在所有平台上都可用。更多详情请参见[确认投递](./confirmed-delivery)。                                                           |
| Push Clicked               | `message.push.clicked`               | 用户点击推送通知以在设备上打开应用。                                                                                                    |
| Push Failed                | `message.push.failed`                | 推送发送失败。详情请参见[推送消息报告](./push-notification-message-reports)。                                                            |
| Push Unsubscribed          | `message.push.unsubscribed`          | 用户取消订阅推送[订阅](./subscriptions)。参见[推送订阅状态何时更新？](./subscriptions#when-do-push-subscription-statuses-update%3F)。          |
| In-App Impression          | `message.iam.impression`             | 应用内消息成功在设备上显示。                                                                                                        |
| In-App Clicked             | `message.iam.clicked`                | 用户点击了应用内消息上的元素。                                                                                                       |
| In-App Page Displayed      | `message.iam.page_displayed`         | 应用内消息页面已显示。对跟踪轮播很有帮助。                                                                                                 |
| Email Sent                 | `message.email.sent`                 | 电子邮件成功发送。                                                                                                             |
| Email Received             | `message.email.received`             | 收件人接收到电子邮件。                                                                                                           |
| Email Opened               | `message.email.opened`               | 收件人打开了电子邮件。详情请参见[电子邮件消息报告](./email-message-reports)。                                                                  |
| Email Link Clicked         | `message.email.clicked`              | 用户点击了电子邮件中的链接。                                                                                                        |
| Email Unsubscribed         | `message.email.unsubscribed`         | 用户通过[取消订阅链接](./unsubscribe-links-email-subscriptions)取消订阅电子邮件。                                                        |
| Email Reported As Spam     | `message.email.reported_as_spam`     | 用户将电子邮件报告为垃圾邮件。Gmail 需要[Google Postmaster 工具](./google-postmaster-tools)来跟踪。更多详情请参见[电子邮件送达性](./email-deliverability)。 |
| Email Bounced              | `message.email.bounced`              | 由于永久错误，电子邮件退回给发送者。详情请参见[电子邮件消息报告](./email-message-reports)。                                                           |
| Email Failed               | `message.email.failed`               | 电子邮件无法投递。详情请参见[电子邮件消息报告](./email-message-reports)。                                                                    |
| Email Suppressed           | `message.email.suppressed`           | 由于电子邮件地址在[抑制列表](./email-deliverability)中，电子邮件无法发送。                                                                    |
| SMS Sent                   | `message.sms.sent`                   | 短信发送给收件人。                                                                                                             |
| SMS Failed                 | `message.sms.failed`                 | 短信发送失败。详情请参见 [SMS 消息报告](./sms-message-reports)。                                                                       |
| SMS Delivered              | `message.sms.delivered`              | 短信成功送达。                                                                                                               |
| SMS Undelivered            | `message.sms.undelivered`            | 短信无法发送。详情请参见 [SMS 消息报告](./sms-message-reports)。                                                                       |
| Live Activity Sent         | `message.live_activity.sent`         | Live Activity 成功发送到 FCM/APNS。                                                                                         |
| Live Activity Delivered    | `message.live_activity.delivered`    | 收件人接收到 Live Activity。                                                                                                 |
| Live Activity Unsubscribed | `message.live_activity.unsubscribed` | 用户取消订阅 Live Activities。                                                                                               |
| Live Activity Failed       | `message.live_activity.failed`       | Live Activity 发送失败。                                                                                                   |
| Live Activity Clicked      | `message.live_activity.clicked`      | 用户点击了 Live Activity。                                                                                                  |

### 示例事件对象

将此 Liquid 模板复制到您的事件流正文中以捕获所有事件字段：

```json JSON theme={null}
{
  "event.kind": "{{ event.kind }}",
  "event.id": "{{ event.id }}",
  "event.timestamp": "{{ event.timestamp }}",
  "event.datetime": "{{ event.datetime }}",
  "event.app_id": "{{ event.app_id }}",
  "event.subscription_device_type": "{{ event.subscription_device_type }}",
  "event.subscription_id": "{{ event.subscription_id }}",
  "event.onesignal_id": "{{ event.onesignal_id }}",
  "event.external_id": "{{ event.external_id }}",
  "event.data.page_name": "{{ event.data.page_name }}",
  "event.data.page_id": "{{ event.data.page_id }}",
  "event.data.target_name": "{{ event.data.target_name }}",
  "event.data.target_id": "{{ event.data.target_id }}",
  "event.data.failure_reason": "{{ event.data.failure_reason }}"
}
```

<Accordion title="示例渲染输出">
  推送点击事件经过 Liquid 渲染后的样子：

  ```json JSON theme={null}
  {
    "event.kind": "message.push.clicked",
    "event.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event.timestamp": 1708559115,
    "event.datetime": "2024-02-21T23:45:15.228Z",
    "event.app_id": "your-onesignal-app-id",
    "event.subscription_device_type": "iOS",
    "event.subscription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "event.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "event.external_id": "user_12345",
    "event.data.page_name": "",
    "event.data.page_id": "",
    "event.data.target_name": "",
    "event.data.target_id": "",
    "event.data.failure_reason": ""
  }
  ```

  `event.data.page_name` 等渠道特定字段对于不包含它们的事件类型为空。
</Accordion>

***

## `message` 属性

`message` 对象描述发送给最终用户的消息，包括其 ID、模板、内容和 URL。

<ParamField body="message.id" type="UUID">
  OneSignal 生成的消息 ID。**Liquid：** `{{ message.id }}`
</ParamField>

<ParamField body="message.name" type="string">
  在控制台中设置或使用 API `name` 属性设置的消息名称。**Liquid：** `{{ message.name }}`
</ParamField>

<ParamField body="message.title" type="object">
  推送消息标题或电子邮件主题。对于推送，返回类似 `{'en':'Your title'}` 的本地化对象。对于电子邮件，返回纯字符串形式的主题行。通过控制台或 API `headings` / `email_subject` 属性设置。**Liquid：** `{{ message.title }}`
</ParamField>

<ParamField body="message.contents" type="object">
  推送或短信消息内容（截取为 50 个字符）。不提供电子邮件内容（`email_body`）。通过控制台或 API `contents` 属性设置。**Liquid：** `{{ message.contents }}`
</ParamField>

<ParamField body="message.template_id" type="UUID">
  通过 Journeys 或 API `template_id` 属性发送的消息的模板 ID。**Liquid：** `{{ message.template_id }}`
</ParamField>

<ParamField body="message.url" type="string">
  使用与 Web 和应用无关的单个 URL 时的消息启动 URL。详情请参见 [URL、链接和深度链接](./links)。**Liquid：** `{{ message.url }}`
</ParamField>

<ParamField body="message.app_url" type="string">
  使用独立的 Web 和应用 URL 时的应用专用启动 URL。详情请参见 [URL、链接和深度链接](./links)。**Liquid：** `{{ message.app_url }}`
</ParamField>

<ParamField body="message.web_url" type="string">
  使用独立的 Web 和应用 URL 时的 Web 专用启动 URL。详情请参见 [URL、链接和深度链接](./links)。**Liquid：** `{{ message.web_url }}`
</ParamField>

<ParamField body="message.live_activity_event_kind" type="string">
  Live Activity 操作类型：`start`、`update` 或 `end`。仅存在于 `message.live_activity.*` 事件中。**Liquid：** `{{ message.live_activity_event_kind }}`
</ParamField>

### 示例消息对象

将此 Liquid 模板复制到您的事件流正文中以捕获所有消息字段：

```json JSON theme={null}
{
  "message.id": "{{ message.id }}",
  "message.name": "{{ message.name }}",
  "message.title": "{{ message.title }}",
  "message.contents": "{{ message.contents }}",
  "message.template_id": "{{ message.template_id }}",
  "message.url": "{{ message.url }}",
  "message.app_url": "{{ message.app_url }}",
  "message.web_url": "{{ message.web_url }}"
}
```

<Accordion title="示例渲染输出">
  推送通知消息：

  ```json JSON theme={null}
  {
    "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
    "message.name": "weekly-promo-push",
    "message.title": "{'en':'Flash Sale: 50% Off Today'}",
    "message.contents": "{'en':'Shop now and save on select items'}",
    "message.template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message.url": "https://example.com/sale",
    "message.app_url": "",
    "message.web_url": ""
  }
  ```

  电子邮件消息 — `message.title` 为纯字符串形式的主题行，`message.contents` 为空，因为电子邮件正文内容不包含在事件流数据中：

  ```json JSON theme={null}
  {
    "message.id": "e2d3c4b5-a6f7-8901-bcde-f12345678901",
    "message.name": "onboarding-welcome-email",
    "message.title": "Welcome to Acme — here's how to get started",
    "message.contents": "",
    "message.template_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "message.url": "",
    "message.app_url": "",
    "message.web_url": ""
  }
  ```
</Accordion>

***

## `user` 属性

`user` 对象包含接收消息的用户的个人资料级数据。

<ParamField body="user.onesignal_id" type="string">
  用户的 OneSignal ID。**Liquid：** `{{ user.onesignal_id }}`
</ParamField>

<ParamField body="user.external_id" type="string">
  用户的外部 ID。**Liquid：** `{{ user.external_id }}`
</ParamField>

<ParamField body="user.tags" type="object">
  用户的[标签](./add-user-data-tags)。使用 `{{ user.tags }}` 访问完整对象，或使用 `{{ user.tags.your_tag }}` 访问特定标签。使用默认值处理缺失标签：`{{ user.tags.your_tag | default: '' }}`。
</ParamField>

<ParamField body="user.language" type="string">
  用户的语言代码。**Liquid：** `{{ user.language }}`
</ParamField>

***

## `subscription` 属性

这些属性描述接收消息的[订阅](./subscriptions)。

<ParamField body="user.subscription.id" type="string">
  订阅的 OneSignal ID。**Liquid：** `{{ user.subscription.id }}`
</ParamField>

<ParamField body="user.subscription.app_id" type="string">
  OneSignal 应用 ID。**Liquid：** `{{ user.subscription.app_id }}`
</ParamField>

<ParamField body="user.subscription.subscription_token" type="string">
  订阅的平台特定令牌。对于**电子邮件**，这是电子邮件地址。对于**短信**，是 E.164 格式的电话号码。对于**推送**，是推送令牌。**Liquid：** `{{ user.subscription.subscription_token }}`
</ParamField>

<ParamField body="user.subscription.session_count" type="number">
  此订阅记录的会话总数。**Liquid：** `{{ user.subscription.session_count }}`
</ParamField>

<ParamField body="user.subscription.language" type="string">
  订阅上设置的语言代码。**Liquid：** `{{ user.subscription.language }}`
</ParamField>

<ParamField body="user.subscription.game_version" type="string">
  订阅报告的应用或游戏版本。**Liquid：** `{{ user.subscription.game_version }}`
</ParamField>

<ParamField body="user.subscription.last_active" type="number">
  订阅最近一次会话的 UNIX 时间戳。**Liquid：** `{{ user.subscription.last_active }}`
</ParamField>

<ParamField body="user.subscription.play_time" type="number">
  此订阅记录的总游戏时间（秒）。**Liquid：** `{{ user.subscription.play_time }}`
</ParamField>

<ParamField body="user.subscription.amount_spent" type="number">
  此订阅记录的应用内购买总额。**Liquid：** `{{ user.subscription.amount_spent }}`
</ParamField>

<ParamField body="user.subscription.created_at" type="number">
  订阅创建时的 UNIX 时间戳。**Liquid：** `{{ user.subscription.created_at }}`
</ParamField>

<ParamField body="user.subscription.subscribed" type="boolean">
  订阅当前是否已选择加入。**Liquid：** `{{ user.subscription.subscribed }}`
</ParamField>

<ParamField body="user.subscription.sdk" type="string">
  订阅设备上的 OneSignal SDK 版本。**Liquid：** `{{ user.subscription.sdk }}`
</ParamField>

<ParamField body="user.subscription.device_model" type="string">
  设备硬件型号（例如 "iPhone14,2"、"Pixel 7"）。**Liquid：** `{{ user.subscription.device_model }}`
</ParamField>

<ParamField body="user.subscription.device_os" type="string">
  设备操作系统和版本（例如 "iOS 17.2"、"Android 14"）。**Liquid：** `{{ user.subscription.device_os }}`
</ParamField>

***

## 相关页面

<Columns cols={2}>
  <Card title="Event Streams" icon="bolt" href="./event-streams">
    设置和配置 Event Streams，包括设置、正文模板和调试。
  </Card>

  <Card title="使用 Liquid 语法" icon="code" href="./using-liquid-syntax">
    用于个性化事件流正文的 Liquid 语法参考。
  </Card>

  <Card title="应用内消息事件流" icon="message" href="./iam-event-streams">
    应用内消息事件数据和轮播跟踪的详情。
  </Card>

  <Card title="指标词汇表" icon="chart-bar" href="./analytics-metrics-glossary">
    各渠道所有消息事件指标的定义。
  </Card>
</Columns>

***

## 常见问题

### 为什么某些事件数据缺失或为空？

Journeys 和 API 发送的消息数据保留 30 天。如果用户在消息发送 30 天后进行交互（点击、打开、取消订阅），相关消息属性可能为空。解决方法是将交互事件中的 `message.id` 与原始 `sent` 事件关联，原始事件包含完整的消息数据。

### `event.id` 和 `message.id` 有什么区别？

`event.id` 是单个事件的唯一标识符（例如一次特定点击）。`message.id` 是已发送消息的标识符——多个事件可以共享相同的 `message.id`（例如，同一推送通知的 `sent` 事件和 `clicked` 事件）。

### 推送和电子邮件的 `message.title` 格式是什么？

对于推送通知，`message.title` 返回类似 `{'en':'Your title'}` 的本地化对象。对于电子邮件，返回纯字符串形式的主题行。格式取决于渠道。

### 事件流中是否包含自定义事件？

不包含。事件流包含**消息事件**（已发送、点击、打开、退回等）——而非[自定义事件](./custom-events)。自定义事件是您发送\_到\_ OneSignal 的用户操作。事件流将消息投递和参与数据从 OneSignal *导出*。

### 如何在事件流正文中引用特定标签？

使用带有精确标签键的 `{{ user.tags.your_tag_key }}`。为避免标签未设置时出错，添加默认值：`{{ user.tags.your_tag_key | default: '' }}`。详情请参见[使用 Liquid 语法](./using-liquid-syntax)。

***