跳转到主要内容

​
概述

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_idUUID事件的唯一标识符
event_timestampTimestamp事件发生时间
event_kindString事件类型
subscription_device_typeString设备类型（例如，iOS、Android、Web、Email、SMS）
languageString订阅语言代码
versionString集成版本
device_osString设备操作系统版本
device_typeNumber数字设备类型
tokenString推送令牌、电话号码或邮箱
subscription_idUUID订阅 ID
subscribedBoolean订阅状态
onesignal_idUUIDOneSignal 用户 ID
last_activeString上次活跃时间戳
sdkStringOneSignal SDK 版本
external_idString应与集成用户 ID 匹配的外部用户 ID
app_idUUID来自 OneSignal 的应用 ID
template_idUUID模板 ID（如适用）
message_idUUID消息批处理/请求 ID
message_nameString消息名称
message_titleString消息标题（仅英语）
message_contentsString截断的消息正文（仅英语）
_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 - 项目级元数据访问权限（推荐）
使用 Google Cloud Console 或 CLI 授予权限：
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.dataViewer

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.jobUser
3

在 OneSignal 中添加集成

在 OneSignal 中，前往 数据 > 集成，然后点击 添加集成。选择 Google BigQuery 并提供：
  • Google Cloud 项目 ID：包含 BigQuery 数据集的 GCP 项目
  • 数据集区域：存储 BigQuery 数据集的位置
  • 服务账户密钥（可选）：如果使用自己的服务账户，则需要 JSON 密钥文件
4

配置事件数据源

指定包含事件数据的 BigQuery 数据集和表：
  • 数据集：BigQuery 数据集名称（例如 analytics_events）
  • 表/视图：包含事件记录的表或视图
  • 事件查询：用于过滤或转换事件数据的可选 SQL 查询
您的事件表应包含以下列：
  • 事件名称/类型
  • 用户标识符
  • 事件时间戳
  • 附加事件属性
5

测试连接

点击 测试连接 以验证 OneSignal 可以访问您的 BigQuery 项目并读取事件数据。

​
事件数据映射

将您的 映射到 OneSignal 的自定义事件格式：
OneSignal 字段描述必需
nameevent_name事件标识符是
external_iduser_id用户标识符是
timestampevent_timestamp事件发生时间否
propertiesevent_data否

​
高级配置

​
自定义 SQL 查询

在同步到 OneSignal 之前，使用自定义 SQL 过滤或转换事件数据： 
SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)

​
跨项目访问

如果您的事件数据跨越多个 BigQuery 项目，请为 OneSignal 服务账户授予对包含引用表或视图的每个项目的访问权限。
您的 BigQuery 连接区域必须与特定表区域匹配以获得最佳性能。

​
常见问题

​
为什么相同内容会有多个消息 ID？

这通常发生在消息模板被在多次发送或触发流中重复使用时。

​
OneSignal 多久同步一次数据？

导出和导入集成都可以每 15 分钟同步一次。

​
我可以使用 BigQuery 视图吗？

可以。只需确保服务账户可以访问视图中引用的所有表。

​
相关资源

⌘I