> ## 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 中选择正确的个性化方法。比较属性、Custom Events、API custom_data、Data Feeds 和 CSV 上传，使用 Liquid 语法发送动态消息。
个性化允许您发送包含动态数据的消息——例如用户姓名、购物车商品、账户余额、预订详情或一次性密码。
本指南帮助您根据以下因素选择正确的个性化方法：
* 您的数据存储在哪里
* 数据是否需要持久化
* 消息是如何触发的
***
## 个性化的工作原理
OneSignal 中的个性化包含两个部分：
1. **Liquid 语法** — 定义值如何在消息中渲染
2. **数据源** — 决定值来自哪里
在发送时，OneSignal 使用选定的数据源解析您的 Liquid 变量。
Liquid 控制格式和逻辑（变量、循环、条件语句）。数据源决定哪些值可用。
**示例：**
```liquid Liquid theme={null}
Hi {{ user.tags.first_name }},
Your verification code is {{ message.custom_data.otp }}.
```
* `user.tags.first_name` 是存储的属性
* `message.custom_data.otp` 是通过 API `custom_data` 字段传递的
***
## 按消息类型划分的支持字段
* 主题、回复和预览文本
* 消息正文
* HTML 块中的图片替换。示例：`
`
* 按钮块操作，如 URL、邮件发送和其他字段。
* 标题（`headings`）、副标题、正文（`contents`）
* 图片 URL
* 启动 URL。示例：`https://example.com/{{last_category_viewed}}`
* 额外的 `data` 不支持 Liquid 语法。
* 消息正文（`contents`）
目前只支持标签替换。
标签必须在用户打开应用开始新会话之前设置。可用的标签在 [`getTags` 方法](./mobile-sdk-reference#gettags)中。
**区块编辑器：**
* 标签替换适用于文本、按钮、图片区块。
**HTML 编辑器：**
* 标签替换适用于：
* 标题 `` 和 `` 标签。示例：`
Hello {{first_name}}!
`
* 元素属性：`["src", "href", "action", "data"]`。示例：``
更多详情和示例请参见[应用内消息 JavaScript API](./in-app-message-api)。
* 在 `event_updates`、`contents` 和 `headings` 属性中。
***
## 数据源
OneSignal 支持五种个性化数据源。使用下表确定哪种来源适合您的用例，然后阅读详细部分以获取实施指导。
| 数据源 | 是什么 | 何时使用 | 是否持久化 | 在 Journeys 中可用 |
| ----------------------------------------- | --------------------------------- | -------------------------------- | ----- | -------------- |
| [**属性**](#properties) | 标签、External ID、订阅数据、应用字段 | 存储在 OneSignal 中的可重用值（姓名、计划、偏好设置） | 是 | 是 |
| [**Custom Events**](#custom-events) | 在 Journey 入口或 Wait Until 时捕获的事件属性 | Journeys 内的行为个性化 | 每个事件 | 仅限 Journey |
| [**API `custom_data`**](#api-custom_data) | 在创建消息 API 中传递的键值对 | 一次性或敏感值（OTP、安全链接、购物车商品） | 否 | 否 |
| [**Data Feeds**](#data-feeds) | 发送时进行的实时 API 调用 | 频繁变化的值（定价、库存、账户余额） | 否 | 是 |
| [**动态内容 CSV**](#dynamic-content-csv) | 在仪表板中上传的 CSV | 每位接收者有不同内容的批量活动 | 每次发送 | 否 |
**常见错误须知**
* 将属性（Tags）用于一次性值，如 OTP 或验证码 — 请改用 `custom_data`
* 期望 `custom_data` 在 Journeys 或后续消息中可用 — 它仅在当前 API 请求中存在
* 假设 Custom Event 属性在事件触发的 Journey 入口或 Wait Until 步骤之外可用
* 将 Data Feeds 用于很少变化的静态数据 — 请改用属性
### 属性
属性包括用户 Tags、External ID、订阅数据和应用级字段。
它们具有以下特点：
* 持久化
* 可重复使用
* 可在消息、模板、[Journey Webhooks](./journeys-webhook) 和 [Event Streams](./event-streams) 中使用。
**何时使用属性：**
* 值已存在于 OneSignal 中
* 值是持久化的
* 您需要在多个活动中重复使用
了解如何引用存储的持久化属性数据。
***
### Custom Events
[Custom Events](./custom-events) 可以使用事件属性在 [Journeys](./journeys-overview) 中个性化消息。
当事件**启动 Journey** 或**匹配 Wait Until 条件**时，OneSignal 会存储该事件，以便其属性可以使用 Liquid 在消息模板中被引用。
**何时使用 Custom Events：**
* 使用 Journeys 的事件触发消息
* 消息应反映事件特定的数据
只有触发 Journey 入口或 Wait Until 步骤的事件才会被存储用于个性化。在这些时刻之外发送的事件不可用于 Journey 消息。
在 Journeys 中使用事件属性的完整指南。
***
### API `custom_data`
[创建消息 API](/reference/create-message) 中的 `custom_data` 字段允许您从后端发送消息特定的值。
此数据：
* 仅在当前请求中存在
* 不会存储在 OneSignal 中
* 不可用于 Journeys
**何时使用 `custom_data`：**
* 发送一次性或敏感值（OTP、安全链接）
* 传递数组（购物车商品、订单行项目、排行榜分数）
* 发送事务性或 API 触发的消息
了解如何传递临时个性化数据。
***
### Data Feeds
[Data Feeds](./data-feeds) 在发送时调用您的 API，并将响应注入您的消息中。
**何时使用 Data Feeds：**
* 您需要在投递时获取最新值
* 数据存储在您的后端
* 值可能在不同发送之间发生变化
在发送时将实时后端数据拉取到消息中。
***
### 动态内容 CSV
在 OneSignal 仪表板中上传 CSV 文件，并使用 Liquid 引用其中的值。
**何时使用 CSV：**
* 为批量活动中的每位接收者自定义不同部分
* 每位接收者的翻译或自定义数据可导出为 CSV 文件
* 您不想使用 API
使用 CSV 上传个性化仪表板活动。
***
## 详细指南
使用以下指南获取分步实施详情和高级示例。
了解如何使用 Liquid 将动态数据插入消息。涵盖变量、条件语句、循环、过滤器、格式化和常见个性化模式。
在发送时从您自己的 API 拉取实时数据。当消息内容依赖于实时后端值（如余额、库存状态或定价）时使用 Data Feeds。
使用用户进入或在 Journey 中进展时捕获的事件属性来个性化 Journey 消息。适用于行为驱动和事件驱动的工作流。
使用存储的用户、订阅、消息和应用程序属性在消息、模板、Journey Webhooks 和 Event Streams 中进行内容个性化。
使用创建消息 API 从您的后端传递每条消息特定的临时数据。最适合 OTP、购物车、数组和批量事务性个性化。
在仪表板中上传 CSV 文件以大规模个性化活动。每行对应一个接收者，可以使用 Liquid 引用。
### 教程
这些指南展示如何在实践中实现个性化。
使用一次性密码、魔法链接或自定义 URL，通过 API 驱动的个性化发送安全验证消息。
构建一个自动化 Journey，检测购物车活动、等待用户不活跃、发送个性化提醒，并在购买后立即让用户退出。
使用 Custom Events、Journeys 和 Data Feeds，根据实时预订状态发送预订确认和恢复消息。
了解如何使用 API 和自动化跨渠道发送收据、提醒、确认和其他事务性消息。
查看使用 Tags 和属性为不同用户和细分群体个性化应用内消息的实际示例。