> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pub/Sub

> 将自定义事件从 Google Pub/Sub 同步到 OneSignal，以基于实时用户行为触发自动化 Journeys 和个性化消息推送活动。

export const PLATFORM_0 = "Pub/Sub"

export const DATA_TYPE_0 = "message fields"

export const COLUMN_HEADER_0 = "Pub/Sub Message Field"

export const PROPERTIES_DESCRIPTION_0 = "JSON object with event details"

## 概览

OneSignal + Google Pub/Sub 集成可以实时将自定义事件从您的 Pub/Sub 主题同步到 OneSignal，以基于用户行为触发自动化消息推送活动和 Journeys。

Pub/Sub 是 Google 的可扩展消息服务，允许应用程序在独立组件之间发送和接收消息。OneSignal 充当您 Pub/Sub 主题的订阅者，允许您同步来自 Pub/Sub 的事件消息以触发个性化用户体验。

***

## 要求

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

### 谷歌发布/订阅

* 启用了 Pub/Sub 的 **Google Cloud 项目**
* 包含事件消息的 **Pub/Sub 主题**
* 用于授予服务账号访问权限的 **IAM 权限**
* 主题上的 **JSON 格式消息**

***

## 设置

<Steps>
  <Step title="创建 Pub/Sub 连接">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    1. 从列表中选择 **Google Pub/Sub**
    2. 输入您的 Pub/Sub 主题所在的 **GCP 项目 ID**
    3. 选择身份验证方法：
       * **自动生成的服务账号**（推荐）：OneSignal 创建并管理服务账号
       * **现有服务账号**：提供您自己的服务账号密钥 JSON 文件
    4. 点击 **连接**
  </Step>

  <Step title="授予服务账号权限">
    OneSignal 将创建一个新的服务账号，并向您提供服务账号的电子邮件地址。

    在您的 GCP 项目上授予此服务账号 **`roles/pubsub.editor`** 角色：

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
      --role roles/pubsub.editor
    ```

    OneSignal 使用此角色来：

    * 创建对您的事件主题的订阅
    * 从主题中消费事件消息
    * 为处理失败创建错误主题（死信队列）
  </Step>

  <Step title="测试连接">
    授予必要权限后，在 OneSignal 中点击 **保存** 来验证连接。

    OneSignal 将验证它是否可以访问您的 Pub/Sub 主题并准备处理事件消息。
  </Step>
</Steps>

***

## 事件数据架构

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

<Steps>
  <Step title="导航到事件架构定义">
    在 OneSignal 中，转到 **数据 > 集成** 并选择您的 Pub/Sub 连接。

    OneSignal 会自动从您的项目中拉取主题列表。点击 **刷新主题** 来手动刷新列表。
  </Step>

  <Step title="定义事件消息架构">
    1. 点击包含您的事件数据的主题名称
    2. 选择 **JSON** 作为消息格式（唯一支持的格式）
    3. 点击 **导入示例消息** 并提供一个示例事件消息
    4. 查看检测到的架构以确保正确的字段映射
    5. 点击 **保存数据集**
  </Step>
</Steps>

### 事件消息格式

您的 Pub/Sub 消息应遵循以下 JSON 结构来用于 OneSignal 自定义事件：

```json theme={null}
{
  "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"
}
```

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

<Warning>
  不要在示例消息中包含客户 PII 或敏感数据。OneSignal 会将消息样本存储作为数据集定义的一部分。
</Warning>

***

## 实时事件处理

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