> ## 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 中的 Properties、Custom Events、custom_data 和 Data Feeds 等个性化数据来源，并使用 Liquid 语法在推送通知、邮件和短信中渲染用户姓名、购物车商品、账户余额或一次性密码等动态内容，发送个性化消息。

[YouTube video player](https://www.youtube.com/embed/71gtwxKWlN8?si=mlgmP6eE3652r_cX)

个性化允许您发送包含动态数据的消息——例如用户姓名、购物车商品、账户余额、预订详情或一次性密码。

本指南帮助您根据以下因素选择正确的个性化方法：

* 您的数据存储在哪里
* 数据是否需要持久化
* 消息是如何触发的

***

## 个性化的工作原理

OneSignal 中的个性化包含两个部分：

1. **Liquid 语法** — 定义值如何在消息中渲染
2. **数据源** — 决定值来自哪里

在发送时，OneSignal 使用选定的数据源解析您的 Liquid 变量。

> [!NOTE]
>
> 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` 字段传递的

***

## 按消息类型划分的支持字段

> [tab] 邮件
>
> * 主题、回复和预览文本
> * 消息正文
> * HTML 块中的图片替换。示例：`<img src="{{image_url}}"/>`
> * 按钮块操作，如 URL、邮件发送和其他字段。

> [tab] 推送
>
> * 标题（`headings`）、副标题、正文（`contents`）
> * 图片 URL
> * 启动 URL。示例：`https://example.com/{{last_category_viewed}}`
> * 额外的 `data` 不支持 Liquid 语法。

> [tab] 短信
>
> * 消息正文（`contents`）

> [tab] 应用内消息
>
> > [!WARNING]
> >
> > 目前只支持标签替换。
> >
> > 标签必须在用户打开应用开始新会话之前设置。可用的标签在 [`getTags` 方法](./mobile-sdk-reference#gettags)中。
>
> **区块编辑器：**
>
> * 标签替换适用于文本、按钮、图片区块。
>
> **HTML 编辑器：**
>
> * 标签替换适用于：
>   * 标题 `<h*>` 和 `<p>` 标签。示例：`<h2>Hello {{first_name}}!</h2>`
>
>   * 元素属性：`["src", "href", "action", "data"]`。示例：`<img src="{{image_url}}"/>`
>
> > [!NOTE]
> >
> > 更多详情和示例请参见[应用内消息 JavaScript API](https://documentation.onesignal.com/docs/cn/in-app-message-api.md)。

> [tab] 实时活动
>
> * 在 `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 | 批量活动或 Journey 消息中每位接收者的不同内容 | 每次发送 | 是 |

> [!WARNING]
>
> **常见错误须知**
>
> * 将属性（Tags）用于一次性值，如 OTP 或验证码 — 请改用 `custom_data`
> * 期望 `custom_data` 在 Journeys 或后续消息中可用 — 它仅在当前 API 请求中存在
> * 假设 Custom Event 属性在事件触发的 Journey 入口或 Wait Until 步骤之外可用
> * 将 Data Feeds 用于很少变化的静态数据 — 请改用属性

### 属性

属性包括用户 Tags、External ID、订阅数据和应用级字段。

它们具有以下特点：

* 持久化
* 可重复使用
* 可在消息、模板、[Journey Webhooks](https://documentation.onesignal.com/docs/cn/journeys-webhook.md) 和 [Event Streams](https://documentation.onesignal.com/docs/cn/event-streams.md) 中使用。

**何时使用属性：**

* 值已存在于 OneSignal 中
* 值是持久化的
* 您需要在多个活动中重复使用

> [card] [使用属性个性化](https://documentation.onesignal.com/docs/cn/personalization-properties-and-tags.md)
>
> 了解如何引用存储的持久化属性数据。

***

### Custom Events

[Custom Events](https://documentation.onesignal.com/docs/cn/custom-events.md) 可以使用事件属性在 [Journeys](https://documentation.onesignal.com/docs/cn/journeys-overview.md) 中个性化消息。

当事件**启动 Journey** 或**匹配 Wait Until 条件**时，OneSignal 会存储该事件，以便其属性可以使用 Liquid 在消息模板中被引用。

**何时使用 Custom Events：**

* 使用 Journeys 的事件触发消息
* 消息应反映事件特定的数据

> [!WARNING]
>
> 只有触发 Journey 入口或 Wait Until 步骤的事件才会被存储用于个性化。在这些时刻之外发送的事件不可用于 Journey 消息。

> [card] [Custom Event 个性化](https://documentation.onesignal.com/docs/cn/personalization-custom-event.md)
>
> 在 Journeys 中使用事件属性的完整指南。

***

### API `custom_data`

[创建消息 API](https://documentation.onesignal.com/reference/create-message.md) 中的 `custom_data` 字段允许您从后端发送消息特定的值。

此数据：

* 仅在当前请求中存在
* 不会存储在 OneSignal 中
* 不可用于 Journeys

**何时使用 `custom_data`：**

* 发送一次性或敏感值（OTP、安全链接）
* 传递数组（购物车商品、订单行项目、排行榜分数）
* 发送事务性或 API 触发的消息

> [card] [使用 API custom\_data 个性化](https://documentation.onesignal.com/docs/cn/personalization-api-custom-data.md)
>
> 了解如何传递临时个性化数据。

***

### Data Feeds

[Data Feeds](https://documentation.onesignal.com/docs/cn/data-feeds.md) 在发送时调用您的 API，并将响应注入您的消息中。

**何时使用 Data Feeds：**

* 您需要在投递时获取最新值
* 数据存储在您的后端
* 值可能在不同发送之间发生变化

> [card] [Data Feeds](https://documentation.onesignal.com/docs/cn/data-feeds.md)
>
> 在发送时将实时后端数据拉取到消息中。

***

### 动态内容 CSV

在 OneSignal 仪表板中上传 CSV 文件，并使用 Liquid 引用其中的值。

**何时使用 CSV：**

* 为批量活动中的每位接收者自定义不同部分
* 每位接收者的翻译或自定义数据可导出为 CSV 文件
* 您不想使用 API

> [card] [动态内容 CSV](https://documentation.onesignal.com/docs/cn/dynamic-content.md)
>
> 使用 CSV 上传个性化仪表板活动。

***

## 详细指南

使用以下指南获取分步实施详情和高级示例。

> [card] [使用 Liquid 语法](https://documentation.onesignal.com/docs/cn/using-liquid-syntax.md)
>
> 了解如何使用 Liquid 将动态数据插入消息。涵盖变量、条件语句、循环、过滤器、格式化和常见个性化模式。

> [card] [Data Feeds](https://documentation.onesignal.com/docs/cn/data-feeds.md)
>
> 在发送时从您自己的 API 拉取实时数据。当消息内容依赖于实时后端值（如余额、库存状态或定价）时使用 Data Feeds。

> [card] [Custom Events 个性化](https://documentation.onesignal.com/docs/cn/personalization-custom-event.md)
>
> 使用用户进入或在 Journey 中进展时捕获的事件属性来个性化 Journey 消息。适用于行为驱动和事件驱动的工作流。

> [card] [属性和 Tags](https://documentation.onesignal.com/docs/cn/personalization-properties-and-tags.md)
>
> 使用存储的用户、订阅、消息和应用程序属性在消息、模板、Journey Webhooks 和 Event Streams 中进行内容个性化。

> [card] [API custom\_data](https://documentation.onesignal.com/docs/cn/personalization-api-custom-data.md)
>
> 使用创建消息 API 从您的后端传递每条消息特定的临时数据。最适合 OTP、购物车、数组和批量事务性个性化。

> [card] [动态内容 CSV](https://documentation.onesignal.com/docs/cn/dynamic-content.md)
>
> 在仪表板中上传 CSV 文件以大规模个性化活动。每行对应一个接收者，可以使用 Liquid 引用。

### 教程

这些指南展示如何在实践中实现个性化。

> [card] [验证、魔法链接和 OTP](https://documentation.onesignal.com/docs/cn/example-verification-magic-link-otp.md)
>
> 使用一次性密码、魔法链接或自定义 URL，通过 API 驱动的个性化发送安全验证消息。

> [card] [废弃购物车 Journey](https://documentation.onesignal.com/docs/cn/abandoned-cart.md)
>
> 构建一个自动化 Journey，检测购物车活动、等待用户不活跃、发送个性化提醒，并在购买后立即让用户退出。

> [card] [预订确认](https://documentation.onesignal.com/docs/cn/booking-confirmations.md)
>
> 使用 Custom Events、Journeys 和 Data Feeds，根据实时预订状态发送预订确认和恢复消息。

> [card] [事务性消息](https://documentation.onesignal.com/docs/cn/transactional-messages.md)
>
> 了解如何使用 API 和自动化跨渠道发送收据、提醒、确认和其他事务性消息。

> [card] [应用内个性化示例](https://documentation.onesignal.com/docs/cn/personalization-properties-and-tags.md)
>
> 查看使用 Tags 和属性为不同用户和细分群体个性化应用内消息的实际示例。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.