跳转到主要内容

​
概览

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 项目内的多个主题定义架构。每个主题可以包含具有各自架构定义的不同事件类型。