> ## 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.

# Google BigQuery

> 将消息事件数据导出到 BigQuery，并从 BigQuery 导入自定义事件以触发个性化活动。

export const PLATFORM_0 = "BigQuery"

export const DATA_TYPE_0 = "event table columns"

export const COLUMN_HEADER_0 = "BigQuery Column"

export const PROPERTIES_DESCRIPTION_0 = "Additional columns as JSON"

## 概述

OneSignal + BigQuery 集成支持两个强大的数据管道：

* **导出**：自动将消息事件数据（推送、电子邮件、短信、应用内）从 OneSignal 发送到 BigQuery 用于分析和报告。
* **导入**：将自定义用户事件从您的 BigQuery 数据集同步到 OneSignal，以触发自动化旅程和个性化消息。

这些集成一起让您对用户参与数据拥有完全的控制——支持高级分析和实时行为驱动的消息传递。

***

## 将 OneSignal 事件导出到 BigQuery

将消息性能和参与事件（例如，发送、打开、点击）发送到 BigQuery 以：

* 构建自定义仪表板和报告
* 跟踪跨渠道的交付和参与趋势
* 将 OneSignal 数据与其他业务数据结合进行分析

**要求**

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

- 具有 **计费已启用** 的 Google Cloud Platform 项目
- 在您的 GCP 项目中启用 BigQuery
- 具有 BigQuery 写入权限的服务帐户

**设置步骤**

### 1. 创建服务帐户

<Steps>
  <Step title="登录您的 Google Cloud Platform 账户">
    登录后，确保选择了正确的项目。

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="创建服务账户">
    访问 [创建服务账户页面](https://console.cloud.google.com/iam-admin/serviceaccounts/create) 并点击 **创建服务账户**。

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="填写字段">
    为其设置任何您选择的名称和服务账户 ID。

    <Frame>
      <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=37236688a79f1c16c0d6fdad15b03245" width="1344" height="870" data-path="images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png" />
    </Frame>
  </Step>

  <Step title="分配 'BigQuery 用户' 角色">
    为服务账户分配 "BigQuery 用户" 角色。

    <Frame>
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=1df75028d3632a3ed413c10c1de9b94a" width="549" height="395" data-path="images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png" />
    </Frame>
  </Step>

  <Step title="为此账户创建 JSON 密钥">
    转到您的新服务账户 > **密钥** > **添加密钥** > **创建新密钥** > 选择 JSON。保存文件。
  </Step>
</Steps>

<Info>
  您需要将此 JSON 密钥文件的全部内容粘贴到 OneSignal 中以激活集成。
</Info>

### 2. 在 OneSignal 中激活集成

<Steps>
  <Step title="转到 OneSignal > 数据 > 集成 > BigQuery" />

  <Step title="粘贴您的服务账户 JSON 密钥" />

  <Step title="配置设置">
    * **同步频率**：最快每 15 分钟一次
    * **数据集/表名称**：如需要可自定义
    * **事件类型**：选择特定的消息事件（例如，已发送、已打开、已点击）
      * **注意**：您可以选择多个事件类型或稍后更新选定的事件。
  </Step>

  <Step title="点击保存并等待确认" />
</Steps>

<Note>
  初始数据同步可能需要 15-30 分钟才能在 BigQuery 中显示。

  在等待过程中，通过推送、电子邮件、应用内或短信发送消息以触发所选事件。
</Note>

### 3. 在 BigQuery 中查看数据

打开您的 BigQuery 控制台并找到数据集（例如 `onesignal_events_<app-id>`）以探索已同步的消息事件。

<Frame caption="包含导出消息事件的 BigQuery 数据集">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=08cf57a8bd91f9447909ad619077935f" width="1552" height="1052" data-path="images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png" />
</Frame>

## 消息事件和属性

### 消息事件类型

**属性：** `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.impression`     | 应用内消息已显示。       |
|       应用内点击      |       `message.iam.clicked`      | 应用内消息已点击。       |
|      应用内页面查看     |   `message.iam.page_displayed`   | 应用内页面已显示。       |
|       邮件已发送      |       `message.email.sent`       | 邮件已送达。          |
|       邮件已接收      |     `message.email.received`     | 邮件已被接收方邮件服务器接受。 |
|       邮件已打开      |      `message.email.opened`      | 用户已打开邮件。        |
|      邮件链接已点击     |      `message.email.clicked`     | 邮件中的链接已点击。      |
|      邮件已取消订阅     |   `message.email.unsubscribed`   | 接收方已取消订阅。       |
|    邮件已标记为垃圾邮件    | `message.email.reported_as_spam` | 用户将您的邮件标记为垃圾邮件。 |
|       邮件已退回      |      `message.email.bounced`     | 由于永久性送达失败而退回。   |
|       邮件失败       |      `message.email.failed`      | 送达失败。           |
|       邮件已抑制      |    `message.email.suppressed`    | 由于抑制列表而被抑制。     |
|       短信已发送      |        `message.sms.sent`        | 短信已发送。          |
|       短信已送达      |      `message.sms.delivered`     | 短信成功送达。         |
|       短信失败       |       `message.sms.failed`       | 短信送达失败。         |
|       短信未送达      |     `message.sms.undelivered`    | 短信被拒绝或无法到达。     |

### 事件数据架构

对于用户生成的每个消息事件，以下元数据将附加到记录中。

|                       列名称                       |     类型    | 描述                                 |
| :---------------------------------------------: | :-------: | ---------------------------------- |
|                    `event_id`                   |    UUID   | 事件的唯一标识符                           |
|                `event_timestamp`                | Timestamp | 事件发生时间                             |
|                   `event_kind`                  |   String  | [事件类型](#message-event-kinds)       |
|            `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  | 截断的消息正文（仅英语）                       |
|                 `failure_reason`                |   String  | 失败原因（适用于推送失败和邮件失败事件）               |
| `_created`, `_id`, `_index`, `_fivetran_synced` |   *内部使用*  | Fivetran 同步元数据                     |

### 注意事项

* 保存/激活后的同步可能需要额外 15-30 分钟才能完成。
* 停用后可能仍会进行最后一次同步。
* 为确保高效的数据同步，我们的系统会自动创建和管理暂存数据集。这些数据集以 `fivetran_{两个随机单词}_staging` 的模式命名，在处理过程中临时存储数据，然后再集成到您的主架构中。这些暂存数据集对于维护流畅的工作流程至关重要，不应删除，因为它们会被自动重新创建。

***

## 从 BigQuery 导入事件

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

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

**要求**

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

- 具有 BigQuery 和事件数据表的 GCP 项目
- 具有读取权限的服务账户
- 在 BigQuery 数据集中包含行为数据的事件数据表

**设置步骤**

<Steps>
  <Step title="创建 BigQuery 服务账户">
    OneSignal 在您创建连接时会自动生成服务账户。或者，您也可以提供自己的服务账户密钥 JSON 文件。

    如果创建自己的服务账户，请确保其具有下面列出的所需权限。
  </Step>

  <Step title="授予所需权限">
    OneSignal 服务账户需要这些 BigQuery IAM 角色：

    * **`bigquery.dataViewer`** - 对包含事件数据的数据集和表的读取访问权限
    * **`bigquery.jobUser`** - 创建数据查询作业的权限
    * **`bigquery.metadataViewer`** - 项目级元数据访问权限（推荐）

    使用 Google Cloud Console 或 CLI 授予权限：

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.dataViewer

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.jobUser
    ```
  </Step>

  <Step title="在 OneSignal 中添加集成">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    选择 **Google BigQuery** 并提供：

    * **Google Cloud 项目 ID**：包含 BigQuery 数据集的 GCP 项目
    * **数据集区域**：存储 BigQuery 数据集的位置
    * **服务账户密钥**（可选）：如果使用自己的服务账户，则需要 JSON 密钥文件
  </Step>

  <Step title="配置事件数据源">
    指定包含事件数据的 BigQuery 数据集和表：

    * **数据集**：BigQuery 数据集名称（例如 `analytics_events`）
    * **表/视图**：包含事件记录的表或视图
    * **事件查询**：用于过滤或转换事件数据的可选 SQL 查询

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

    * 事件名称/类型
    * 用户标识符
    * 事件时间戳
    * 附加事件属性
  </Step>

  <Step title="测试连接">
    点击 **测试连接** 以验证 OneSignal 可以访问您的 BigQuery 项目并读取事件数据。
  </Step>
</Steps>

***

### 事件数据映射

将您的 {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} | 否  |

### 高级配置

#### 自定义 SQL 查询

在同步到 OneSignal 之前，使用自定义 SQL 过滤或转换事件数据：

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
```

#### 跨项目访问

如果您的事件数据跨越多个 BigQuery 项目，请为 OneSignal 服务账户授予对包含引用表或视图的每个项目的访问权限。

<Warning>
  您的 BigQuery 连接区域必须与特定表区域匹配以获得最佳性能。
</Warning>

***

## 常见问题

### 为什么相同内容会有多个消息 ID？

这通常发生在消息模板被在多次发送或触发流中重复使用时。

### OneSignal 多久同步一次数据？

导出和导入集成都可以每 15 分钟同步一次。

### 我可以使用 BigQuery 视图吗？

可以。只需确保服务账户可以访问视图中引用的所有表。

***

## 相关资源

* [Creating service account keys in GCP](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating)
* [OneSignal Journeys documentation](./journeys-overview)
* [OneSignal Data Export documentation](./exporting-data)

***