Event Stream 数据参考

使用 Liquid 语法访问事件流数据。将任意字段包装在 {{ }} 中以在事件流正文中包含它。查看示例。

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

`event` 属性

每个事件都包含以下核心字段。event.data.* 下的渠道特定字段仅在适用时包含 — 请参见渠道特定字段。

event.kind

string

事件类型，结合渠道和操作（例如 message.push.clicked、message.email.bounced）。请参阅下面事件类型参考中的完整值列表。Liquid： {{ event.kind }}

event.id

UUID

OneSignal 为每个独立事件生成的唯一标识符，采用 UUID v4 格式。使用此 ID 进行幂等投递跟踪。如需消息或模板标识符，请使用 message.id 或 message.template_id。Liquid： {{ event.id }}

event.timestamp

integer

事件的 UNIX 时间戳。Liquid： {{ event.timestamp }}

event.datetime

string

事件在 UTC 时间的人类可读时间，格式为 ISO 8601 字符串（例如 “2024-02-21T23:45:15.228Z”）。Liquid： {{ event.datetime }}

event.app_id

UUID

OneSignal 应用 ID。Liquid： {{ event.app_id }}

event.subscription_device_type

string

订阅类型（例如 iOS、Android、Chrome、Email、SMS）。Liquid： {{ event.subscription_device_type }}

event.subscription_id

UUID

OneSignal 订阅 ID。Liquid： {{ event.subscription_id }}

event.onesignal_id

UUID

OneSignal 用户 ID。Liquid： {{ event.onesignal_id }}

event.external_id

string

您设置为 OneSignal 外部 ID 别名的用户 ID。如果未设置，可能为空。Liquid： {{ event.external_id }}

渠道特定字段

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

应用内消息事件

包含于 message.iam.* 事件。详情请参见应用内消息事件流。

event.data.page_name

string

显示的应用内消息页面或卡片的名称。Liquid： {{ event.data.page_name }}

event.data.page_id

string

显示的应用内消息页面或卡片的唯一标识符。Liquid： {{ event.data.page_id }}

event.data.target_name

string

被点击的按钮或图像块元素的名称。该元素必须包含应用内点击操作。Liquid： {{ event.data.target_name }}

event.data.target_id

string

被点击的按钮或图像块元素的唯一标识符。Liquid： {{ event.data.target_id }}

Live Activity 事件

包含于 message.live_activity.* 事件。

event.data.live_activity_id

string

特定 Live Activity 的唯一标识符（例如 “Knicks vs Cavs - Oct 22 7PM”）。Liquid： {{ event.data.live_activity_id }}

event.data.live_activity_type

string

Live Activity 类别的分组标签（例如 “Knicks_games”）。Liquid： {{ event.data.live_activity_type }}

失败事件

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

event.data.failure_reason

string

消息发送失败的原因。常见原因请参见推送消息报告或电子邮件消息报告。Liquid： {{ event.data.failure_reason }}

事件类型参考

每个指标的详细定义，请参见指标词汇表。

消息事件类型（OneSignal）	事件名称（在数据集中）	事件描述
Push Sent	`message.push.sent`	推送通知成功发送到推送服务（FCM、APNS 等）。
Push Received	`message.push.received`	收件人接收到推送通知。并非在所有平台上都可用。更多详情请参见确认投递。
Push Clicked	`message.push.clicked`	用户点击推送通知以在设备上打开应用。
Push Failed	`message.push.failed`	推送发送失败。详情请参见推送消息报告。
Push Unsubscribed	`message.push.unsubscribed`	用户取消订阅推送订阅。参见推送订阅状态何时更新？。
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 Link Clicked	`message.email.clicked`	用户点击了电子邮件中的链接。
Email Unsubscribed	`message.email.unsubscribed`	用户通过取消订阅链接取消订阅电子邮件。
Email Reported As Spam	`message.email.reported_as_spam`	用户将电子邮件报告为垃圾邮件。Gmail 需要Google Postmaster 工具来跟踪。更多详情请参见电子邮件送达性。
Email Bounced	`message.email.bounced`	由于永久错误，电子邮件退回给发送者。详情请参见电子邮件消息报告。
Email Failed	`message.email.failed`	电子邮件无法投递。详情请参见电子邮件消息报告。
Email Suppressed	`message.email.suppressed`	由于电子邮件地址在抑制列表中，电子邮件无法发送。
SMS Sent	`message.sms.sent`	短信发送给收件人。
SMS Failed	`message.sms.failed`	短信发送失败。详情请参见 SMS 消息报告。
SMS Delivered	`message.sms.delivered`	短信成功送达。
SMS Undelivered	`message.sms.undelivered`	短信无法发送。详情请参见 SMS 消息报告。
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

{
  "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 }}"
}

示例渲染输出

推送点击事件经过 Liquid 渲染后的样子：

JSON

{
  "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 等渠道特定字段对于不包含它们的事件类型为空。

`message` 属性

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

message.id

UUID

OneSignal 生成的消息 ID。Liquid： {{ message.id }}

message.name

string

在控制台中设置或使用 API name 属性设置的消息名称。Liquid： {{ message.name }}

message.title

object

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

message.contents

object

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

message.template_id

UUID

通过 Journeys 或 API template_id 属性发送的消息的模板 ID。Liquid： {{ message.template_id }}

message.url

string

使用与 Web 和应用无关的单个 URL 时的消息启动 URL。详情请参见 URL、链接和深度链接。Liquid： {{ message.url }}

message.app_url

string

使用独立的 Web 和应用 URL 时的应用专用启动 URL。详情请参见 URL、链接和深度链接。Liquid： {{ message.app_url }}

message.web_url

string

使用独立的 Web 和应用 URL 时的 Web 专用启动 URL。详情请参见 URL、链接和深度链接。Liquid： {{ message.web_url }}

message.live_activity_event_kind

string

Live Activity 操作类型：start、update 或 end。仅存在于 message.live_activity.* 事件中。Liquid： {{ message.live_activity_event_kind }}

示例消息对象

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

JSON

{
  "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 }}"
}

示例渲染输出

推送通知消息：

JSON

{
  "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

{
  "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": ""
}

`user` 属性

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

user.onesignal_id

string

用户的 OneSignal ID。Liquid： {{ user.onesignal_id }}

user.external_id

string

用户的外部 ID。Liquid： {{ user.external_id }}

user.tags

object

用户的标签。使用 {{ user.tags }} 访问完整对象，或使用 {{ user.tags.your_tag }} 访问特定标签。使用默认值处理缺失标签：{{ user.tags.your_tag | default: '' }}。

user.language

string

用户的语言代码。Liquid： {{ user.language }}

`subscription` 属性

这些属性描述接收消息的订阅。

user.subscription.id

string

订阅的 OneSignal ID。Liquid： {{ user.subscription.id }}

user.subscription.app_id

string

OneSignal 应用 ID。Liquid： {{ user.subscription.app_id }}

user.subscription.subscription_token

string

订阅的平台特定令牌。对于电子邮件，这是电子邮件地址。对于短信，是 E.164 格式的电话号码。对于推送，是推送令牌。Liquid： {{ user.subscription.subscription_token }}

user.subscription.session_count

number

此订阅记录的会话总数。Liquid： {{ user.subscription.session_count }}

user.subscription.language

string

订阅上设置的语言代码。Liquid： {{ user.subscription.language }}

user.subscription.game_version

string

订阅报告的应用或游戏版本。Liquid： {{ user.subscription.game_version }}

user.subscription.last_active

number

订阅最近一次会话的 UNIX 时间戳。Liquid： {{ user.subscription.last_active }}

user.subscription.play_time

number

此订阅记录的总游戏时间（秒）。Liquid： {{ user.subscription.play_time }}

user.subscription.amount_spent

number

此订阅记录的应用内购买总额。Liquid： {{ user.subscription.amount_spent }}

user.subscription.created_at

number

订阅创建时的 UNIX 时间戳。Liquid： {{ user.subscription.created_at }}

user.subscription.subscribed

boolean

订阅当前是否已选择加入。Liquid： {{ user.subscription.subscribed }}

user.subscription.sdk

string

订阅设备上的 OneSignal SDK 版本。Liquid： {{ user.subscription.sdk }}

user.subscription.device_model

string

设备硬件型号（例如 “iPhone14,2”、“Pixel 7”）。Liquid： {{ user.subscription.device_model }}

user.subscription.device_os

string

设备操作系统和版本（例如 “iOS 17.2”、“Android 14”）。Liquid： {{ user.subscription.device_os }}

Event Streams

设置和配置 Event Streams，包括设置、正文模板和调试。

使用 Liquid 语法

用于个性化事件流正文的 Liquid 语法参考。

应用内消息事件流

应用内消息事件数据和轮播跟踪的详情。

指标词汇表

各渠道所有消息事件指标的定义。

常见问题

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

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'} 的本地化对象。对于电子邮件，返回纯字符串形式的主题行。格式取决于渠道。

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

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

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

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

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

Event Stream 数据参考

`event` 属性

渠道特定字段

应用内消息事件

Live Activity 事件

失败事件

事件类型参考

示例事件对象

`message` 属性

示例消息对象

`user` 属性

`subscription` 属性

相关页面

Event Streams

使用 Liquid 语法

应用内消息事件流

指标词汇表

常见问题

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

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

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

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

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

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

​event 属性

​渠道特定字段

​应用内消息事件

​Live Activity 事件

​失败事件

​事件类型参考

​示例事件对象

​message 属性

​示例消息对象

​user 属性

​subscription 属性

​相关页面

Event Streams

使用 Liquid 语法

应用内消息事件流

指标词汇表

​常见问题

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

​event.id 和 message.id 有什么区别？

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

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

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

`event` 属性

渠道特定字段

应用内消息事件

Live Activity 事件

失败事件

事件类型参考

示例事件对象

`message` 属性

示例消息对象

`user` 属性

`subscription` 属性

相关页面

常见问题

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

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

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

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

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