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

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

export const PLATFORM_0 = "Google Sheets"

export const DATA_TYPE_0 = "columns"

export const COLUMN_HEADER_0 = "Sheets Column Examples"

export const PROPERTIES_DESCRIPTION_0 = "Multiple columns combined into JSON"

## 概览

OneSignal + Google Sheets 集成可以自动将自定义事件从您的 Google Sheets 同步到 OneSignal。这允许您基于存储在电子表格中的用户行为数据触发自动化 Journeys 和个性化消息推送活动，非常适合协作管理事件数据的团队。

***

## 要求

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

### 谷歌表格

* 能够访问包含事件数据的工作表的 **Google 账户**
* 具有适当列结构用于事件数据的 **事件电子表格**
* OneSignal 访问数据所需的 **工作表共享权限**
* 事件跟踪工作表中的 **一致数据格式**

***

## 设置

<Steps>
  <Step title="准备您的事件数据工作表">
    使用事件数据所需的列来结构您的 Google Sheet：

    **必需列：**

    * `event_name` 或 `event_type`：事件名称（字符串）
    * `user_id` 或 `email`：用户标识符（字符串）
    * `timestamp` 或 `created_at`：事件时间戳（日期/日期时间）
    * `properties`：事件属性作为 JSON 或单独的列（可选）

    **示例工作表结构：**

    ```
    | event_name | user_id | timestamp           | product_id | amount |
    |------------|---------|---------------------|------------|--------|
    | purchase   | user123 | 2024-01-15 10:30:00 | prod_abc   | 29.99  |
    | signup     | user456 | 2024-01-15 11:45:00 |            |        |
    ```
  </Step>

  <Step title="配置工作表权限">
    与 OneSignal 的服务账户共享您的 Google Sheet：

    1. 打开您的 Google Sheet
    2. 点击右上角的 **共享** 按钮
    3. 添加 OneSignal 的服务账户电子邮件（在设置过程中提供）
    4. 将权限设置为 **查看者**（只读访问）
    5. 点击 **发送** 来授予访问权限

    <Info>
      OneSignal 将在集成设置过程中提供特定的服务账户电子邮件。
    </Info>
  </Step>

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

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

    * **工作表 URL**：您的 Google Sheet 的完整 URL
    * **工作表名称**：包含事件数据的特定选项卡/工作表名称
    * **标题行**：包含列标题的行号（通常为 1）
    * **数据范围**：包含您的事件数据的单元格范围（例如，`A2:F1000`）
  </Step>

  <Step title="配置列映射">
    将您的 Google Sheets 列映射到 OneSignal 事件字段：

    * **事件名称列**：选择包含事件名称的列
    * **用户 ID 列**：选择包含用户标识符的列
    * **时间戳列**：选择包含事件时间戳的列
    * **属性列**：选择要作为事件属性包含的附加列

    <Info>
      您可以将多列映射为事件属性。OneSignal 会将它们组合成一个单一的事件载荷。
    </Info>
  </Step>

  <Step title="设置同步计划">
    配置 OneSignal 检查新事件数据的频率：

    * **同步频率**：从 15 分钟、每小时或每天中选择
    * **增量同步**：启用以仅同步上次更新后的新行
    * **时间戳筛选器**：仅同步特定时间范围内的事件

    <Warning>
      Google Sheets 具有 API 速率限制。对于大型数据集的工作表，更频繁的同步可能会被限速。
    </Warning>
  </Step>

  <Step title="测试连接">
    点击 **测试连接** 来验证 OneSignal 可以访问您的 Google Sheet 并正确读取事件数据。
  </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} | 否  |

***

## 高级配置

### 增量同步设置

配置增量同步以仅处理新事件：

1. **时间戳列**：确保您的工作表具有一致的时间戳列
2. **排序顺序**：按时间戳排序事件（最新的在最后）
3. **仅附加**：将新事件添加到工作表底部
4. **避免编辑**：同步后不要修改历史事件行

### 数据验证

在您的 Google Sheet 中实施数据验证：

```
数据 > 数据验证
- 事件名称：从范围列表（预定义的事件类型）
- 用户 ID：自定义公式来检查格式
- 时间戳：日期/时间格式验证
- 金额：数字属性的数字验证
```

### 协作工作流

团队协作的最佳实践：

* **命名范围**：为事件数据部分使用命名范围
* **受保护的范围**：保护标题行免受意外更改
* **注释**：添加注释来解释事件定义
* **版本历史**：使用 Google Sheets 的版本历史来跟踪更改
* **访问控制**：限制数据录入团队成员的编辑访问权限

### 性能优化

针对大型数据集进行优化：

* **工作表限制**：为获得最佳性能，将单个工作表保持在10,000行以下
* **多个工作表**：为不同的事件类型使用单独的工作表
* **数据存档**：每月将旧数据存档到单独的工作表
* **公式**：尽量减少事件数据范围中的复杂公式

<Warning>
  Google Sheets 在总共低于 50,000 个单元格时性能最佳。对于大量事件跟踪，请考虑使用数据库源。
</Warning>

***

## 常见问题

### OneSignal 多久从 Google Sheets 同步一次事件？

OneSignal 可以频繁地每 15 分钟同步一次，但我们建议大多数使用情况采用每小时或每天同步，以遵守 Google 的 API 限制。

### 多个团队成员可以向同一工作表添加事件吗？

是的，Google Sheets 支持实时协作。但是，确保团队成员了解所需的数据格式和列结构。

### 如果有人编辑历史事件数据会发生什么？

OneSignal 基于时间戳和行位置进行同步。编辑历史数据可能会导致重复事件或数据不一致。我们建议采用仅追加的工作流。