概览
OneSignal + Google Pub/Sub 集成可以实时将自定义事件从您的 Pub/Sub 主题同步到 OneSignal,以基于用户行为触发自动化消息推送活动和 Journeys。 Pub/Sub 是 Google 的可扩展消息服务,允许应用程序在独立组件之间发送和接收消息。OneSignal 充当您 Pub/Sub 主题的订阅者,允许您同步来自 Pub/Sub 的事件消息以触发个性化用户体验。要求
- 访问自定义事件(目前处于测试阶段)
- 升级账户计划(免费应用不可用)。
谷歌发布/订阅
- 启用了 Pub/Sub 的 Google Cloud 项目
- 包含事件消息的 Pub/Sub 主题
- 用于授予服务账号访问权限的 IAM 权限
- 主题上的 JSON 格式消息
设置
1
创建 Pub/Sub 连接
在 OneSignal 中,前往 数据 > 集成,然后点击 添加集成。
- 从列表中选择 Google Pub/Sub
- 输入您的 Pub/Sub 主题所在的 GCP 项目 ID
- 选择身份验证方法:
- 自动生成的服务账号(推荐):OneSignal 创建并管理服务账号
- 现有服务账号:提供您自己的服务账号密钥 JSON 文件
- 点击 连接
2
授予服务账号权限
OneSignal 将创建一个新的服务账号,并向您提供服务账号的电子邮件地址。在您的 GCP 项目上授予此服务账号 OneSignal 使用此角色来:
roles/pubsub.editor
角色:- 创建对您的事件主题的订阅
- 从主题中消费事件消息
- 为处理失败创建错误主题(死信队列)
3
测试连接
授予必要权限后,在 OneSignal 中点击 保存 来验证连接。OneSignal 将验证它是否可以访问您的 Pub/Sub 主题并准备处理事件消息。
事件数据架构
在您可以将 Pub/Sub 主题用于自定义事件之前,您必须定义事件消息的架构。1
导航到事件架构定义
在 OneSignal 中,转到 数据 > 集成 并选择您的 Pub/Sub 连接。OneSignal 会自动从您的项目中拉取主题列表。点击 刷新主题 来手动刷新列表。
2
定义事件消息架构
- 点击包含您的事件数据的主题名称
- 选择 JSON 作为消息格式(唯一支持的格式)
- 点击 导入示例消息 并提供一个示例事件消息
- 查看检测到的架构以确保正确的字段映射
- 点击 保存数据集
事件消息格式
您的 Pub/Sub 消息应遵循以下 JSON 结构来用于 OneSignal 自定义事件:事件数据映射
将您的 映射到 OneSignal 的自定义事件格式:OneSignal 字段 | 描述 | 必需 | |
---|---|---|---|
name | event_name | 事件标识符 | 是 |
external_id | user_id | 用户标识符 | 是 |
timestamp | event_timestamp | 事件发生时间 | 否 |
properties | event_data | 否 |
不要在示例消息中包含客户 PII 或敏感数据。OneSignal 会将消息样本存储作为数据集定义的一部分。
实时事件处理
与批处理集成不同,Pub/Sub 支持近乎实时的事件处理:- 低延迟:事件在发布到主题后数秒内被处理
- 自动订阅:OneSignal 为每个主题创建专用订阅
- 错误处理:失败的事件被发送到死信队列主题以供调查
- 可扩展处理:自动处理大量事件流
高级配置
死信队列
OneSignal 会自动为处理失败的事件创建错误主题:- 自动创建:为每个订阅创建错误主题
- 失败事件存储:无法处理的事件被存储以供调试
- 手动审查:通过 Google Cloud Console 访问失败事件以进行故障排除
消息确认
OneSignal 自动处理 Pub/Sub 消息确认:- 成功处理:消息在成功创建事件后被确认
- 处理失败:消息被负面确认并发送到死信队列
- 重试逻辑:针对暂时性故障的内置重试处理
限制
- 仅支持 JSON 消息格式
- 消息样本作为数据集定义的一部分存储(避免 PII)
- 需要项目级别的
roles/pubsub.editor
权限 - 最大消息大小遵循 Google Pub/Sub 限制(10MB)