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

# 标签

> 使用OneSignal数据标签存储用户属性和跟踪事件，实现高级细分和个性化消息传递。

数据标签是键值对，让您能在OneSignal中存储自定义属性和跟踪用户行为。它们可实现强大的细分、自动化和个性化。

使用标签来：

* 存储用户特征，如`subscription_tier`或`name`
* 跟踪行为，如`purchases`、`clicks`或`levels`
* 为消息和Journeys细分用户
* 个性化消息内容

***

## 数据标签值格式规则

<Note>
  **重要提示：** 所有标签值必须是**字符串**。您仍然可以存储数字、时间戳和布尔值——只需将它们字符串化即可。
</Note>

| 值类型   | 格式示例                                | 说明                                            |
| ----- | ----------------------------------- | --------------------------------------------- |
| 字符串标签 | `"free"`, `"VIP"`                   | 用于用户类型、权限、状态                                  |
| 数字    | `"42"`, `"3.14"`                    | 支持数字过滤器（`大于`、`小于`）                            |
| 时间戳   | `"1685400000"`                      | Unix时间戳（以秒为单位）。与[时间运算符](./time-operators)配合使用 |
| 布尔值   | `"true"` / `"false"`, `"1"` / `"0"` | 使用`"1"`/`"0"`以减少载荷大小                          |

<Warning>
  **不支持：** 数组、对象、嵌套值或JSON数据块。
</Warning>

### 受限关键词

以下关键词是受限的，不应用作标签键，因为它们在内部用于消息个性化：
`message`、`notification`、`subscription`、`user`、`template`、`app`、`org`、`dynamic_content`、`data_feed`、`journey`、`custom_data`

更多详情请参阅[消息个性化](./message-personalization)。

***

## 推荐的标签策略

数据标签应该代表您想要在**消息或受众细分中使用**的信息。它们不是用来存储完整的用户配置文件或日志的——请使用您的后端数据库来处理这些。

***

### 基于事件的行为标签

使用标签跟踪用户行为。非常适合触发Journey、后续消息或提醒。

| 键                 | 值示例                       | 描述                                               |
| ----------------- | ------------------------- | ------------------------------------------------ |
| `cart_update`     | `"1685400000"`            | 用户最后一次向购物车添加商品的时间。配合[时间运算符](./time-operators)使用。 |
| `last_order`      | `"1684100000"`            | 最后一次完成购买的时间戳                                     |
| `amount_spent`    | `"100"`                   | 总消费金额——字符串化的数字，不含货币符号                            |
| `social_share`    | `"2"`                     | 社交分享或推荐的次数                                       |
| `tutorial_status` | `"step2"` 或 `"completed"` | 教程进度——使用可读或编号的字符串值                               |

***

### 游戏活动标签

游戏使用这些标签基于用户表现进行个性化。

| 键            | 值示例      | 描述       |
| ------------ | -------- | -------- |
| `points`     | `"1250"` | 经验值或游戏积分 |
| `level`      | `"8"`    | 当前游戏等级   |
| `high_score` | `"3000"` | 达到的最高分数  |

***

### 账户状态标签

使用这些标签根据账户等级或状态变化来定位用户。

| 键                 | 值示例                    | 描述        |
| ----------------- | ---------------------- | --------- |
| `user_type`       | `"free"`, `"premium"`  | 订阅或访问层级   |
| `has_downgraded`  | `"1"` 或 `"1685400000"` | 布尔值或降级时间戳 |
| `user_privileges` | `"admin"`, `"guest"`   | 基于角色的细分   |

<Note>
  使用**External ID**来识别单个用户。**不要**为此目的使用标签。请参阅[External ID](./users#external-id)和[别名](./aliases)。
</Note>

***

### 个性化标签

非常适合使用[变量替换](./message-personalization)进行基于姓名的消息定制。

| 键            | 值示例               | 描述      |
| ------------ | ----------------- | ------- |
| `first_name` | `"Jon"`           | 名字      |
| `last_name`  | `"Smith"`         | 姓氏      |
| `user_name`  | `"PokeCatcher22"` | 显示名或用户名 |

***

### 位置和人口统计标签

按地区或年龄细分用户。

| 键            | 值示例             | 描述                                                              |
| ------------ | --------------- | --------------------------------------------------------------- |
| `region`     | `"New York"`    | 都市區域，可选使用[ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) |
| `postcode`   | `"94105"`       | 邮编或邮政编码                                                         |
| `location`   | `"Downtown LA"` | 自定义字符串位置                                                        |
| `birthdate`  | `"915148800"`   | Unix时间戳（以秒为单位，出生日期）                                             |
| `birth_year` | `"1998"`        | 四位数出生年份                                                         |
| `age_range`  | `"18-35"`       | 适用于一般受众细分                                                       |

***

## 添加、更新和删除标签的方法

您可以根据用例和技术设置使用下列任意方法来管理标签：

<Columns cols={2}>
  <Card title="SDK Methods (Recommended)">
    在用户执行操作时从您的应用程序或网站实时设置标签。

    * → [Mobile SDK 参考](./mobile-sdk-reference)
    * → [Web SDK 参考](./web-sdk-reference)
  </Card>

  <Card title="REST API" href="/reference/update-user">
    使用我们的REST API在服务器端添加、更新或删除标签。
  </Card>

  <Card title="Journeys" href="./journeys-overview">
    在用户通过Journey步骤时自动应用标签。
  </Card>

  <Card title="CSV Import" href="./import">
    通过上传包含`external_id`或`subscription_id`的CSV文件批量更新用户标签。
  </Card>

  <Card title="Web Category Prompts" href="./permission-requests">
    提示用户自选兴趣爱好，并将其存储为标签。
  </Card>

  <Card title="In-App Messages" href="./in-app-messages-setup">
    基于应用内消息点击操作收集或更新标签。
  </Card>

  <Card title="Manual Entry">
    直接从 OneSignal 控制台编辑标签。

    * 转到 **Audience > Users > User Profile > Tags**
  </Card>

  <Card title="Third-Party Integrations" href="./integrations">
    一些集成支持自动同步标签。

    * Segment、HubSpot、Mixpanel 等
  </Card>
</Columns>

***

## 导入和清理数据标签

### 通过CSV编辑或删除标签

1. 从控制台或API[导出用户数据](./exporting-data)。
2. 通过留空单元格来删除标签值。
3. 在[CSV导入](./import)过程中，启用：
   * "当上传值为空时删除现有数据标签值"
4. 保存并上传您更新的CSV。

***

## 常见问题

### 我可以为每个用户设置多少个标签？

取决于您的套餐。查看您的[套餐限制](https://onesignal.com/pricing)或[联系销售](https://onesignal.com/contact)以增加您的配额。

### 如果我超出了套餐限制，我的标签会怎么样？

* 已设置的标签将保持不变。
* 您仍然可以读取它们。
* 对于达到或超出限制的用户，您**无法添加或更新**标签。
* 您必须先删除标签，然后发送第二个请求来添加新标签。

示例：

* 限制 = 20 个标签/用户
* 用户有 19 个标签：
  * ✅ 添加 1 个新标签 = 成功
  * ❌ 添加 2+ 个新标签 = 失败
* 用户有 20 个标签：
  * ❌ 添加任何新标签 = 失败

### 我在哪里可以检查标签使用情况？

* 控制台：**Audience > Users > Tags 列**
* 导出用户以获取完整视图

### 如何减少标签使用量？

* 使用 SDK 或 API 删除标签
* 使用 CSV 导入批量删除
* 使用更少、更可重用的标签（例如，`status:active`）

<Info>
  需要帮助？

  与我们的支持团队聊天或发送邮件至 `support@onesignal.com`

  请包含以下信息：

  * 您遇到的问题详情以及复现步骤（如有）
  * 您的 OneSignal 应用 ID
  * 外部 ID 或订阅 ID（如适用）
  * 您在 OneSignal 控制台中测试的消息 URL（如适用）
  * 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)

  我们很乐意为您提供帮助！
</Info>

***