跳转到主要内容

概览

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 中,前往 数据 > 集成,然后点击 添加集成
  1. 从列表中选择 Google Pub/Sub
  2. 输入您的 Pub/Sub 主题所在的 GCP 项目 ID
  3. 选择身份验证方法:
    • 自动生成的服务账号(推荐):OneSignal 创建并管理服务账号
    • 现有服务账号:提供您自己的服务账号密钥 JSON 文件
  4. 点击 连接
2

授予服务账号权限

OneSignal 将创建一个新的服务账号,并向您提供服务账号的电子邮件地址。在您的 GCP 项目上授予此服务账号 roles/pubsub.editor 角色:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
  --role roles/pubsub.editor
OneSignal 使用此角色来:
  • 创建对您的事件主题的订阅
  • 从主题中消费事件消息
  • 为处理失败创建错误主题(死信队列)
3

测试连接

授予必要权限后,在 OneSignal 中点击 保存 来验证连接。OneSignal 将验证它是否可以访问您的 Pub/Sub 主题并准备处理事件消息。

事件数据架构

在您可以将 Pub/Sub 主题用于自定义事件之前,您必须定义事件消息的架构。
1

导航到事件架构定义

在 OneSignal 中,转到 数据 > 集成 并选择您的 Pub/Sub 连接。OneSignal 会自动从您的项目中拉取主题列表。点击 刷新主题 来手动刷新列表。
2

定义事件消息架构

  1. 点击包含您的事件数据的主题名称
  2. 选择 JSON 作为消息格式(唯一支持的格式)
  3. 点击 导入示例消息 并提供一个示例事件消息
  4. 查看检测到的架构以确保正确的字段映射
  5. 点击 保存数据集

事件消息格式

您的 Pub/Sub 消息应遵循以下 JSON 结构来用于 OneSignal 自定义事件:
{
  "event_name": "purchase_completed",
  "user_id": "user_12345",
  "timestamp": "2023-12-01T10:30:00Z",
  "properties": {
    "product_id": "prod_abc123",
    "price": 29.99,
    "category": "electronics",
    "payment_method": "credit_card"
  },
  "session_id": "session_789"
}

事件数据映射

将您的 映射到 OneSignal 的自定义事件格式:
OneSignal 字段描述必需
nameevent_name事件标识符
external_iduser_id用户标识符
timestampevent_timestamp事件发生时间
propertiesevent_data
不要在示例消息中包含客户 PII 或敏感数据。OneSignal 会将消息样本存储作为数据集定义的一部分。

实时事件处理

与批处理集成不同,Pub/Sub 支持近乎实时的事件处理:
  • 低延迟:事件在发布到主题后数秒内被处理
  • 自动订阅:OneSignal 为每个主题创建专用订阅
  • 错误处理:失败的事件被发送到死信队列主题以供调查
  • 可扩展处理:自动处理大量事件流

高级配置

死信队列

OneSignal 会自动为处理失败的事件创建错误主题:
  • 自动创建:为每个订阅创建错误主题
  • 失败事件存储:无法处理的事件被存储以供调试
  • 手动审查:通过 Google Cloud Console 访问失败事件以进行故障排除

消息确认

OneSignal 自动处理 Pub/Sub 消息确认:
  • 成功处理:消息在成功创建事件后被确认
  • 处理失败:消息被负面确认并发送到死信队列
  • 重试逻辑:针对暂时性故障的内置重试处理

限制

  • 仅支持 JSON 消息格式
  • 消息样本作为数据集定义的一部分存储(避免 PII)
  • 需要项目级别的 roles/pubsub.editor 权限
  • 最大消息大小遵循 Google Pub/Sub 限制(10MB)

常见问题

事件处理速度如何?

事件通常在发布到您的 Pub/Sub 主题后数秒内被处理,支持近乎实时的 Journey 触发。

如果 OneSignal 无法处理事件会怎样?

失败的事件会自动发送到 OneSignal 创建的死信队列主题。您可以在 Google Cloud Console 中查看这些事件以进行调试。

我可以为不同的事件类型使用多个主题吗?

是的,您可以为同一 GCP 项目内的多个主题定义架构。每个主题可以包含具有各自架构定义的不同事件类型。
I