跳转到主要内容

概述

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