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 仓库详细信息

登录到您的 Databricks 工作区

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

选择您的仓库

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

保存以下详细信息

服务器主机名
端口
HTTP 路径

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

2. 创建服务主体

转到服务主体页面

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

添加新的服务主体

点击添加服务主体，然后点击添加新建。

命名服务主体

为其命名（例如 onesignal-sync）。

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

3. 生成密钥

点击进入创建的主体

转到密钥选项卡

生成密钥

点击生成密钥并安全保存。

密钥只显示一次—请安全存储。

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

4. 分配权限

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

点击授权

为服务主体分配以下权限

USE CATALOG
USE SCHEMA
SELECT
MODIFY
CREATE SCHEMA
CREATE TABLE

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

5. 连接 OneSignal

激活集成

在 OneSignal 中，导航到数据 > 集成 > Databricks。

输入详细信息

服务器主机名
端口
HTTP 路径
目录名称
架构名称
服务主体凭据（ID + 密钥）

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

配置集成

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

选择事件

选择您希望在 Databricks 目录中接收的事件。

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

完成设置

点击保存并等待成功确认

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

6. 在 Databricks 中查看数据

在 Databricks 中打开您的目录。
同步完成后，您配置的架构将出现。
访问并查询 message_events 表。
Databricks 目录视图，显示生产架构下的 OneSignal 消息事件表。
点击进入表以预览示例数据。
来自 message_events_1 表的示例数据，包含同步的 OneSignal 事件字段。

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

消息事件和属性

消息事件类型

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

从 Databricks 导入事件

将行为事件数据从 Databricks 发送到 OneSignal 以：

根据用户活动触发旅程
基于行为数据个性化消息

要求

访问自定义事件（目前处于测试阶段）
升级账户计划（免费应用不可用）。

具有 SQL 仓库或计算集群的 Databricks 工作区
具有适当权限的个人访问令牌
包含 Delta Lake 格式行为数据的事件数据表
Unity Catalog（推荐用于数据治理）

设置步骤

创建 Databricks 个人访问令牌

生成个人访问令牌供 OneSignal 访问您的 Databricks 工作区：

在您的 Databricks 工作区中导航到用户设置
点击开发者选项卡，然后点击访问令牌
点击生成新令牌
输入注释（如”OneSignal Integration”）并设置过期时间（推荐 90 天）
保存生成的令牌（您将在 OneSignal 中需要此令牌）

配置 SQL 仓库访问

确保 OneSignal 可以通过 SQL 仓库查询您的事件数据：

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

授予表权限

向 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`;

在 OneSignal 中添加集成

在 OneSignal 中，前往 数据 > 集成，然后点击 添加集成。选择 Databricks 并提供：

服务器主机名：您的 Databricks SQL 仓库主机名
HTTP 路径：SQL 仓库 HTTP 路径
个人访问令牌：在步骤 1 中创建的令牌
目录（可选）：如果使用 Unity Catalog，则为 Unity Catalog 名称

配置事件数据源

指定包含您事件数据的 Databricks 表：

数据库/架构：包含事件表的数据库或架构名称
表：包含事件记录的表名称（例如 user_events）
事件查询：用于过滤或转换事件数据的可选 SQL 查询

您的事件表应包含以下列：

事件名称/类型（字符串）
用户标识符（字符串）
事件时间戳（时间戳）
其他事件属性

测试连接

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

事件数据映射

将您的映射到 OneSignal 的自定义事件格式：

OneSignal 字段	描述	必需
`name`	`event_name`	事件标识符	是
`external_id`	`user_id`	用户标识符	是
`timestamp`	`event_timestamp`	事件发生时间	否
`properties`	`event_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_id 和 event_name 进行 Z 排序以提高过滤性能
Delta Lake 功能：使用液体聚类进行自动优化

流式事件处理

对于实时事件处理，请考虑：

结构化流：在事件到达时处理事件
Delta Live Tables：构建稳健的事件处理管道
Auto Loader：持续摄取新的事件文件

确保您的 SQL 仓库具有足够的计算资源来处理 OneSignal 的查询，而不会影响其他工作负载。

常见问题

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

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

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

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

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

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

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

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

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

概览