跳转到主要内容
OneSignal Databricks 集成

OneSignal Databricks 集成概览


概览

OneSignal + Databricks 集成支持双向数据同步
  • 将 OneSignal 消息事件导出到 Databricks 用于分析、仪表板和报告。
  • 从 Databricks 导入自定义事件到 OneSignal 以触发旅程和个性化活动。
使用此集成来统一您的参与度和行为数据跨平台,并推动数据驱动的消息传递策略。

将 OneSignal 事件导出到 Databricks

将推送、电子邮件、应用内和 SMS 事件从 OneSignal 同步到您的 Databricks 湖仓,以实现近实时分析和可见性。 要求
  • 专业计划
  • 启用自定义事件(用于事件导入)
  • Databricks 平台:AWS、Azure 或 GCP
  • Databricks 计划:高级或更高版本
  • Databricks Unity Catalog(推荐用于治理)
  • 用于查询的 Databricks SQL 仓库
  • Delta Lake 事件表(用于自定义事件导入)
设置步骤

1. 收集 SQL 仓库详细信息

1

登录到您的 Databricks 工作区

在您的 Databricks 工作区中转到 SQL 仓库
2

选择您的仓库

选择您的仓库并打开连接详细信息选项卡。
3

保存以下详细信息

  • 服务器主机名
  • 端口
  • HTTP 路径
用于 Fivetran 设置的 Databricks SQL 连接详细信息

用于 Fivetran 设置的 Databricks SQL 连接详细信息

2. 创建服务主体

1

转到服务主体页面

转到工作区设置 > 身份和访问 > 服务主体
2

添加新的服务主体

点击添加服务主体,然后点击添加新建
3

命名服务主体

为其命名(例如 onesignal-sync)。
添加服务主体的模态窗口,突出显示'添加新建'选项

添加服务主体的模态窗口,突出显示'添加新建'选项

3. 生成密钥

1

点击进入创建的主体

2

转到密钥选项卡

3

生成密钥

点击生成密钥并安全保存。
密钥只显示一次—请安全存储。
显示用于 API 身份验证的 OAuth 密钥和客户端 ID 的 Databricks'生成密钥'模态窗口

显示用于 API 身份验证的 OAuth 密钥和客户端 ID 的 Databricks'生成密钥'模态窗口

4. 分配权限

1

导航到您的目录并打开权限选项卡

2

点击授权

3

为服务主体分配以下权限

  • USE CATALOG
  • USE SCHEMA
  • SELECT
  • MODIFY
  • CREATE SCHEMA
  • CREATE TABLE
为 Databricks 主体分配权限的屏幕,已选择自定义目录权限

为 Databricks 主体分配权限的屏幕,已选择自定义目录权限。

5. 连接 OneSignal

1

激活集成

在 OneSignal 中,导航到数据 > 集成 > Databricks
2

输入详细信息

  • 服务器主机名
  • 端口
  • HTTP 路径
  • 目录名称
  • 架构名称
  • 服务主体凭据(ID + 密钥)
OneSignal Databricks 配置表单,包含目录、主机名、HTTP 路径和 OAuth 凭据字段

OneSignal Databricks 配置表单,包含目录、主机名、HTTP 路径和 OAuth 凭据字段。

3

配置集成

  • 同步频率: 最频繁每 15 分钟一次
  • 数据集/表名: 预设为 onesignal_events_<app-id>message_events(可编辑)
  • 事件类型: 选择要同步的事件—选择全部或只选择您需要的
4

选择事件

选择您希望在 Databricks 目录中接收的事件。
OneSignal 事件导出设置屏幕,显示同步状态、数据集配置和选定的消息事件类型

OneSignal 事件导出设置屏幕,显示同步状态、数据集配置和选定的消息事件类型。

5

完成设置

点击保存并等待成功确认
初始数据同步可能需要 15-30 分钟才能在 BigQuery 中显示。在等待期间,通过推送、电子邮件、应用内或 SMS 发送消息以触发选定的事件。

6. 在 Databricks 中查看数据

  1. 在 Databricks 中打开您的目录
  2. 同步完成后,您配置的架构将出现。
  3. 访问并查询 message_events 表。
    Databricks 目录视图,显示生产架构下的 OneSignal 消息事件表

    Databricks 目录视图,显示生产架构下的 OneSignal 消息事件表。

  4. 点击进入表以预览示例数据。
    来自 message_events_1 表的示例数据,包含同步的 OneSignal 事件字段

    来自 message_events_1 表的示例数据,包含同步的 OneSignal 事件字段。

如果您遇到缺少架构、权限错误或格式错误的事件等问题,请联系 support@onesignal.com

消息事件和属性

消息事件类型

属性: 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 的模式命名,在处理过程中临时存储数据,然后再集成到您的主架构中。这些暂存数据集对于维护流畅的工作流程至关重要,不应删除,因为它们会被自动重新创建。

从 Databricks 导入事件

将行为事件数据从 Databricks 发送到 OneSignal 以:
  • 根据用户活动触发旅程
  • 基于行为数据个性化消息
要求
  • 访问自定义事件(目前处于测试阶段)
  • 升级账户计划(免费应用不可用)。
  • 具有 SQL 仓库或计算集群的 Databricks 工作区
  • 具有适当权限的个人访问令牌
  • 包含 Delta Lake 格式行为数据的事件数据表
  • Unity Catalog(推荐用于数据治理)
设置步骤
1

创建 Databricks 个人访问令牌

生成个人访问令牌供 OneSignal 访问您的 Databricks 工作区:
  1. 在您的 Databricks 工作区中导航到用户设置
  2. 点击开发者选项卡,然后点击访问令牌
  3. 点击生成新令牌
  4. 输入注释(如”OneSignal Integration”)并设置过期时间(推荐 90 天)
  5. 保存生成的令牌(您将在 OneSignal 中需要此令牌)
2

配置 SQL 仓库访问

确保 OneSignal 可以通过 SQL 仓库查询您的事件数据:
  1. 在您的 Databricks 工作区中导航到 SQL 仓库
  2. 为 OneSignal 访问选择或创建 SQL 仓库
  3. 从连接详细信息中记下服务器主机名HTTP 路径
  4. 确保仓库可以访问您的事件数据表
3

授予表权限

向 OneSignal 授予对包含事件数据的表的读取访问权限:
-- 对于启用了 Unity Catalog 的工作区
GRANT SELECT ON TABLE catalog.schema.event_table TO `onesignal@yourdomain.com`;

-- 对于 Hive 元存储表
GRANT SELECT ON TABLE database.event_table TO `onesignal@yourdomain.com`;
4

在 OneSignal 中添加集成

在 OneSignal 中,前往 数据 > 集成,然后点击 添加集成选择 Databricks 并提供:
  • 服务器主机名:您的 Databricks SQL 仓库主机名
  • HTTP 路径:SQL 仓库 HTTP 路径
  • 个人访问令牌:在步骤 1 中创建的令牌
  • 目录(可选):如果使用 Unity Catalog,则为 Unity Catalog 名称
5

配置事件数据源

指定包含您事件数据的 Databricks 表:
  • 数据库/架构:包含事件表的数据库或架构名称
  • :包含事件记录的表名称(例如 user_events
  • 事件查询:用于过滤或转换事件数据的可选 SQL 查询
您的事件表应包含以下列:
  • 事件名称/类型(字符串)
  • 用户标识符(字符串)
  • 事件时间戳(时间戳)
  • 其他事件属性
6

测试连接

点击测试连接以验证 OneSignal 可以访问您的 Databricks 工作区并读取事件数据。

事件数据映射

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

高级配置

Unity Catalog 集成

利用 Unity Catalog 进行受管理的数据访问:
SELECT
  event_name,
  user_id,
  event_timestamp,
  to_json(
    named_struct(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp() - INTERVAL 7 DAYS

Delta Lake 优化

为更好的查询性能优化事件表:
  • 分区:按日期(event_date)分区以加快基于时间的查询
  • Z-Ordering:按 user_idevent_name 进行 Z 排序以提高过滤性能
  • Delta Lake 功能:使用液体聚类进行自动优化

流式事件处理

对于实时事件处理,请考虑:
  • 结构化流:在事件到达时处理事件
  • Delta Live Tables:构建稳健的事件处理管道
  • Auto Loader:持续摄取新的事件文件
确保您的 SQL 仓库具有足够的计算资源来处理 OneSignal 的查询,而不会影响其他工作负载。

常见问题

为什么我看到具有相同内容的不同消息 ID?

当同一消息发送多次时会发生这种情况,可能通过事务流程或跨多个发送重用的消息模板。

OneSignal 从 Databricks 同步事件的频率如何?

OneSignal 根据您配置的计划同步事件数据,最小间隔为 15 分钟。

我可以使用 Databricks 笔记本进行事件处理吗?

是的,您可以使用笔记本处理和准备事件数据,然后通过 OneSignal 可以查询的表公开它。

事件查询的成本优化如何?

考虑使用无服务器 SQL 仓库以获得经济高效的按需计算,它会根据查询负载自动扩展。
I