概述
OneSignal + BigQuery 集成支持两个强大的数据管道:- 导出:自动将消息事件数据(推送、电子邮件、短信、应用内)从 OneSignal 发送到 BigQuery 用于分析和报告。
- 导入:将自定义用户事件从您的 BigQuery 数据集同步到 OneSignal,以触发自动化旅程和个性化消息。
将 OneSignal 事件导出到 BigQuery
将消息性能和参与事件(例如,发送、打开、点击)发送到 BigQuery 以:- 构建自定义仪表板和报告
- 跟踪跨渠道的交付和参与趋势
- 将 OneSignal 数据与其他业务数据结合进行分析
- 访问自定义事件(目前处于测试阶段)
- 升级账户计划(免费应用不可用)。
- 具有 计费已启用 的 Google Cloud Platform 项目
- 在您的 GCP 项目中启用 BigQuery
- 具有 BigQuery 写入权限的服务帐户
1. 创建服务帐户
1
登录您的 Google Cloud Platform 账户
登录后,确保选择了正确的项目。

2
创建服务账户
访问 创建服务账户页面 并点击 创建服务账户。

3
填写字段
为其设置任何您选择的名称和服务账户 ID。

4
分配 'BigQuery 用户' 角色
为服务账户分配 “BigQuery 用户” 角色。

5
为此账户创建 JSON 密钥
转到您的新服务账户 > 密钥 > 添加密钥 > 创建新密钥 > 选择 JSON。保存文件。
您需要将此 JSON 密钥文件的全部内容粘贴到 OneSignal 中以激活集成。
2. 在 OneSignal 中激活集成
1
转到 OneSignal > 数据 > 集成 > BigQuery
2
粘贴您的服务账户 JSON 密钥
3
配置设置
- 同步频率:最快每 15 分钟一次
- 数据集/表名称:如需要可自定义
- 事件类型:选择特定的消息事件(例如,已发送、已打开、已点击)
- 注意:您可以选择多个事件类型或稍后更新选定的事件。
4
点击保存并等待确认
初始数据同步可能需要 15-30 分钟才能在 BigQuery 中显示。在等待过程中,通过推送、电子邮件、应用内或短信发送消息以触发所选事件。
3. 在 BigQuery 中查看数据
打开您的 BigQuery 控制台并找到数据集(例如onesignal_events_<app-id>
)以探索已同步的消息事件。

包含导出消息事件的 BigQuery 数据集
消息事件和属性
消息事件类型
属性:event_kind
类型: String
消息和事件的类型(例如 message.push.received
、message.push.sent
)。
消息事件 (OneSignal) | event_kind | 描述 |
---|---|---|
推送已发送 | message.push.sent | 推送通知成功发送。 |
推送已接收 | message.push.received | 推送确认已送达并被用户接收。 |
推送已点击 | message.push.clicked | 用户点击了推送。 |
推送失败 | message.push.failed | 送达失败。查看消息报告。 |
推送已取消订阅 | message.push.unsubscribed | 用户取消订阅推送。 |
应用内展示 | message.iam.displayed | 应用内消息已显示。 |
应用内点击 | message.iam.clicked | 应用内消息已点击。 |
应用内页面查看 | message.iam.pagedisplayed | 应用内页面已显示。 |
邮件已发送 | message.email.sent | 邮件已送达。 |
邮件已接收 | message.email.received | 邮件已被接收方邮件服务器接受。 |
邮件已打开 | message.email.opened | 用户已打开邮件。 |
邮件链接已点击 | message.email.clicked | 邮件中的链接已点击。 |
邮件已取消订阅 | message.email.unsubscribed | 接收方已取消订阅。 |
邮件已标记为垃圾邮件 | message.email.resporedasspam | 用户将您的邮件标记为垃圾邮件。 |
邮件已退回 | message.email.hardbounced | 由于永久性送达失败而退回。 |
邮件失败 | message.email.failed | 送达失败。 |
邮件已抑制 | message.email.supressed | 由于抑制列表而被抑制。 |
短信已发送 | message.sms.sent | 短信已发送。 |
短信已送达 | message.sms.delivered | 短信成功送达。 |
短信失败 | message.sms.failed | 短信送达失败。 |
短信未送达 | message.sms.undelivered | 短信被拒绝或无法到达。 |
事件数据架构
对于用户生成的每个消息事件,以下元数据将附加到记录中。列名称 | 类型 | 描述 |
---|---|---|
event_id | UUID | 事件的唯一标识符 |
event_timestamp | Timestamp | 事件发生时间 |
event_kind | String | 事件类型 |
subscription_device_type | String | 设备类型(例如,iOS、Android、Web、Email、SMS) |
language | String | 订阅语言代码 |
version | String | 集成版本 |
device_os | String | 设备操作系统版本 |
device_type | Number | 数字设备类型 |
token | String | 推送令牌、电话号码或邮箱 |
subscription_id | UUID | 订阅 ID |
subscribed | Boolean | 订阅状态 |
onesignal_id | UUID | OneSignal 用户 ID |
last_active | String | 上次活跃时间戳 |
sdk | String | OneSignal SDK 版本 |
external_id | String | 应与集成用户 ID 匹配的外部用户 ID |
app_id | UUID | 来自 OneSignal 的应用 ID |
template_id | UUID | 模板 ID(如适用) |
message_id | UUID | 消息批处理/请求 ID |
message_name | String | 消息名称 |
message_title | String | 消息标题(仅英语) |
message_contents | String | 截断的消息正文(仅英语) |
_created , _id , _index , _fivetran_synced | 内部使用 | Fivetran 同步元数据 |
注意事项
- 保存/激活后的同步可能需要额外 15-30 分钟才能完成。
- 停用后可能仍会进行最后一次同步。
- 为确保高效的数据同步,我们的系统会自动创建和管理暂存数据集。这些数据集以
fivetran_{两个随机单词}_staging
的模式命名,在处理过程中临时存储数据,然后再集成到您的主架构中。这些暂存数据集对于维护流畅的工作流程至关重要,不应删除,因为它们会被自动重新创建。
从 BigQuery 导入事件
将行为事件数据从 BigQuery 发送到 OneSignal 以:- 基于用户活动触发旅程
- 基于行为数据个性化消息
- 访问自定义事件(目前处于测试阶段)
- 升级账户计划(免费应用不可用)。
- 具有 BigQuery 和事件数据表的 GCP 项目
- 具有读取权限的服务账户
- 在 BigQuery 数据集中包含行为数据的事件数据表
1
创建 BigQuery 服务账户
OneSignal 在您创建连接时会自动生成服务账户。或者,您也可以提供自己的服务账户密钥 JSON 文件。如果创建自己的服务账户,请确保其具有下面列出的所需权限。
2
授予所需权限
OneSignal 服务账户需要这些 BigQuery IAM 角色:
bigquery.dataViewer
- 对包含事件数据的数据集和表的读取访问权限bigquery.jobUser
- 创建数据查询作业的权限bigquery.metadataViewer
- 项目级元数据访问权限(推荐)
3
在 OneSignal 中添加集成
在 OneSignal 中,前往 数据 > 集成,然后点击 添加集成。选择 Google BigQuery 并提供:
- Google Cloud 项目 ID:包含 BigQuery 数据集的 GCP 项目
- 数据集区域:存储 BigQuery 数据集的位置
- 服务账户密钥(可选):如果使用自己的服务账户,则需要 JSON 密钥文件
4
配置事件数据源
指定包含事件数据的 BigQuery 数据集和表:
- 数据集:BigQuery 数据集名称(例如
analytics_events
) - 表/视图:包含事件记录的表或视图
- 事件查询:用于过滤或转换事件数据的可选 SQL 查询
- 事件名称/类型
- 用户标识符
- 事件时间戳
- 附加事件属性
5
测试连接
点击 测试连接 以验证 OneSignal 可以访问您的 BigQuery 项目并读取事件数据。
事件数据映射
将您的 映射到 OneSignal 的自定义事件格式:OneSignal 字段 | 描述 | 必需 | |
---|---|---|---|
name | event_name | 事件标识符 | 是 |
external_id | user_id | 用户标识符 | 是 |
timestamp | event_timestamp | 事件发生时间 | 否 |
properties | event_data | 否 |
高级配置
自定义 SQL 查询
在同步到 OneSignal 之前,使用自定义 SQL 过滤或转换事件数据:跨项目访问
如果您的事件数据跨越多个 BigQuery 项目,请为 OneSignal 服务账户授予对包含引用表或视图的每个项目的访问权限。您的 BigQuery 连接区域必须与特定表区域匹配以获得最佳性能。
常见问题
为什么相同内容会有多个消息 ID?
这通常发生在消息模板被在多次发送或触发流中重复使用时。OneSignal 多久同步一次数据?
导出和导入集成都可以每 15 分钟同步一次。我可以使用 BigQuery 视图吗?
可以。只需确保服务账户可以访问视图中引用的所有表。相关资源
- Creating service account keys in GCP
- OneSignal Journeys documentation
- OneSignal Data Export documentation