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

# 使用属性进行个性化

> 使用预定义属性和自定义数据 Tags 个性化 OneSignal 消息。通过 Liquid 语法跨电子邮件、推送、短信和 Webhook 访问用户、订阅、Journey、消息、模板和应用级数据。

使用属性（例如用户 Tags 和 External ID 等标识符）通过 [Liquid 语法](./using-liquid-syntax) 个性化消息和投递载荷。

OneSignal **在发送时**渲染 Liquid 占位符，使用已存储在用户、订阅、Journey、消息、模板、应用或组织上的数据。您可以使用这些数据来个性化消息、[Journey Webhook](./journeys-webhook) 和 [Event Streams](./event-streams)。

***

## 何时使用属性个性化

使用属性个性化可在发送时使用 OneSignal 中已有的数据渲染内容——最常见的是用户 Tags、External ID 和订阅字段（如电子邮件或电话号码）。

适用场景：

* 数据已存储在 OneSignal 中
* 您希望在消息发送时自动替换 Liquid 占位符
* 您不需要在投递时获取或计算新数据

<Note>
  如果值必须在发送时获取或计算（例如实时价格或库存），请使用 [Data Feeds](./data-feeds) 或我们的 [API 与 `custom_data`](./personalization-api-custom-data)。

  如果值来自导致用户进入或推进 Journey 的事件，请使用 [Custom Event 个性化](./personalization-custom-event)。
</Note>

### 渠道支持

每个渠道支持特定的属性类型和字段。

<Tabs>
  <Tab title="电子邮件">
    在以下字段中支持[用户和订阅属性](#user-&-subscription-properties)：

    * 主题、回复地址和预标题
    * 消息正文
    * HTML 属性（例如：`<img src="{{ image_url }}" />`）
    * 按钮操作（URL、mailto 等）
  </Tab>

  <Tab title="推送">
    在以下字段中支持[用户和订阅属性](#user-&-subscription-properties)：

    * 标题（`headings`）、副标题、正文（`contents`）
    * 图片 URL
    * 启动 URL：`https://example.com/{{last_category_viewed}}`

    <Warning>
      `data`（附加数据）字段不支持 Liquid 语法。
    </Warning>
  </Tab>

  <Tab title="短信">
    在以下字段中支持[用户和订阅属性](#user-&-subscription-properties)：

    * 消息正文（`contents`）
  </Tab>

  <Tab title="应用内消息">
    仅支持 Tag 替换。属性、Custom Events 和其他数据源目前不可用。

    * Tags 必须在用户开始新的应用会话之前设置。
    * 使用测试发送流程时，Tag 替换可能不会显示。

    **块编辑器：** 文本、按钮和图片块
    **HTML 编辑器：** 文本元素和属性（`src`、`href`、`action`、`data`）
  </Tab>

  <Tab title="实时活动">
    在以下字段中支持[用户和订阅属性](#user-&-subscription-properties)：

    * `event_updates`
    * `contents`
    * `headings`
  </Tab>
</Tabs>

***

## 属性个性化的工作原理

OneSignal 将 Liquid 占位符替换为被发送消息的用户和订阅对应的属性值。

```liquid Liquid theme={null}
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
```

如果用户的 Tags 为 `first_name: Jon` 和 `level: 5`，他们会看到：

```liquid Text theme={null}
Hi Jon!
Congrats on reaching level 5!
```

## 如果用户没有设置 Tags，则会显示默认值。

## 属性 Liquid 对象参考

使用本节查找 Liquid 中可用的确切对象和字段名称。

### 用户和订阅属性

使用 `user` 获取用户级数据。当您需要渠道特定的值（如电子邮件地址或电话号码）时，请使用 `subscription`。

<ParamField body="user.tags">
  用户的 [Tags](./add-user-data-tags)。您可以通过以下几种方式引用 Tags：

  * 直接使用 `key`，或将 key 放在 `tags` 之后
  * 示例 Tags 设置：`first_name: Jon, level: 5`

  ```liquid Liquid theme={null}
  Your first name is {{ first_name }}.
  Your first name is {{ user.tags.first_name }}.
  Your level is {{ level }}.
  Your level is {{ user.tags.level }}.
  ```

  * 使用 for 循环语法遍历 Tags。此示例输出以逗号分隔的 key:value 对。

  ```liquid Liquid theme={null}
  {% for tag in user.tags %}
  {{ tag[0] }}: {{ tag[1] }}
  {% unless forloop.last %},
  {% endunless %}{% endfor %}
  ```
</ParamField>

<ParamField body="user.external_id">
  用户的 [External ID](./users#external-id)。

  ```liquid Liquid theme={null}
  Your user ID is {{ user.external_id }}.
  Your user ID is {{ subscription.external_id }}.
  ```
</ParamField>

<ParamField body="user.onesignal_id">
  用户的 [OneSignal ID](./users)。

  ```liquid Liquid theme={null}
  Your OneSignal user ID is {{ user.onesignal_id }}.
  ```
</ParamField>

<ParamField body="subscription.email">
  接收消息的电子邮件 Subscription 的电子邮件地址。

  ```liquid Liquid theme={null}
  Thanks for subscribing with email {{ subscription.email }}.
  ```
</ParamField>

<ParamField body="subscription.phone_number">
  接收消息的短信 Subscription 的电话号码。

  ```liquid Liquid theme={null}
  Thanks for subscribing with phone number {{ subscription.phone_number }}.
  ```
</ParamField>

<ParamField body="user.language">
  用户的语言代码。

  ```liquid Liquid theme={null}
  Preferred language: {{ user.language }}
  Preferred language: {{ subscription.language }}
  ```
</ParamField>

<ParamField body="user.subscriptions">
  用户的 [Subscriptions](./subscriptions)。

  * 使用 for 循环语法遍历 Subscriptions。
  * 此示例输出每个订阅的 token 和 ID（以逗号分隔）。

  ```json JSON theme={null}
  {
    "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
  }
  ```
</ParamField>

<ParamField body="subscription.unsubscribe_token">
  用于[使用 Token 取消订阅邮件 API](/reference/unsubscribe-with-token) 的 token。

  ```liquid theme={null}
  Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}
  ```
</ParamField>

### Journey 属性

`journey` 对象允许您引用 Journey 名称或访问 Journey 的 [Custom Event 个性化](./personalization-custom-event)。

<ParamField body="journey.name">
  Journey 的名称。

  ```json JSON theme={null}
  {
    "journey_name": "{{ journey.name }}"
  }
  ```
</ParamField>

### 消息属性

`message` 对象提供对消息 ID、名称和模板 ID 的访问，这对 [Event Streams](./event-streams) 很有用，同时还可以访问 [custom\_data](./personalization-api-custom-data) 以个性化从后端发送的消息。

<ParamField body="message.id">
  由 OneSignal 设置的消息 ID。

  ```json theme={null}
  {
    "message_id": "{{ message.id }}"
  }
  ```
</ParamField>

<ParamField body="message.name">
  由发送者设置的消息名称。

  ```json theme={null}
  {
    "message_name": "{{ message.name }}"
  }
  ```
</ParamField>

<ParamField body="message.template_id">
  由 OneSignal 设置的模板 ID。

  ```json theme={null}
  {
    "template_id": "{{ message.template_id }}"
  }
  ```
</ParamField>

### 模板属性

`template` 对象提供对用于发送消息的 [Template](./templates) 的模板 ID 和名称的访问。这对 [Event Streams](./event-streams) 很有用。

<ParamField body="template.id">
  由 OneSignal 设置的模板 ID。

  ```json theme={null}
  {
    "template_id": "{{ template.id }}"
  }
  ```
</ParamField>

<ParamField body="template.name">
  由发送者设置的模板名称。

  ```json theme={null}
  {
    "template_name": "{{ template.name }}"
  }
  ```
</ParamField>

***

### 应用和组织属性

`app` 和 `org` 对象提供发送消息的[应用和组织](./apps-organizations)的详细信息。这对 [Event Streams](./event-streams) 很有用。

<ParamField body="app.id">
  由 OneSignal 设置的应用 ID。

  ```json theme={null}
  {
    "app_id": "{{ app.id }}"
  }
  ```
</ParamField>

<ParamField body="app.name">
  由应用所有者设置的应用名称。

  ```json theme={null}
  {
    "app_name": "{{ app.name }}"
  }
  ```
</ParamField>

<ParamField body="org.id">
  由 OneSignal 设置的组织 ID。

  ```json theme={null}
  {
    "org_id": "{{ org.id }}"
  }
  ```
</ParamField>

<ParamField body="org.name">
  由组织所有者设置的组织名称。

  ```json theme={null}
  {
    "org_name": "{{ org.name }}"
  }
  ```
</ParamField>

***

## 示例：使用 Tags 实现购物车遗弃提醒

本示例展示如何使用用户 Tags 个性化购物车遗弃消息。它基于[购物车遗弃教程](./abandoned-cart)。

**示例 Tags 设置：**

```json JSON theme={null}
{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}
```

### 电子邮件模板

<Steps>
  <Step title="创建新的电子邮件模板">
    导航到 **Messages > Templates > New Email Template** 并打开拖放编辑器。
  </Step>

  <Step title="添加布局结构">
    创建五行：

    * 第 1、2、4 行：一列包含一个 **Paragraph** 块
    * 第 3 行：四列包含 **HTML | Paragraph | Paragraph | Paragraph**
    * 第 5 行：一列包含一个 **Button** 块

    <Frame caption="购物车遗弃电子邮件入门模板">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/starter-template-abandoned-cart.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=551e9ec4618f64fdc0b6ab610a537c48" width="2968" height="2124" data-path="images/email/starter-template-abandoned-cart.png" />
    </Frame>
  </Step>

  <Step title="向段落块添加 Liquid">
    在第 1 行中添加：

    ```liquid Liquid theme={null}
    We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    ```

    在第 2 行中添加用户正在查看内容的描述：

    ```liquid Text theme={null}
    Currently in your cart:
    ```

    在第 4 行中添加另一个行动号召：

    ```liquid Text theme={null}
    Checkout now while supplies last!
    ```
  </Step>

  <Step title="显示最近添加的商品">
    在第 3 行中配置四列：

    **第 1 列（HTML 块）：**

    ```html HTML theme={null}
    <img src="{{product_image}}" alt="Image" style="max-width:100%;" />
    ```

    **第 2–4 列（文本块）：**

    * 第 2 列：`{{product_name}}`
    * 第 3 列：`{{product_quantity}}`
    * 第 4 列：`{{product_price}}`
  </Step>

  <Step title="将购物车 URL 添加到按钮">
    在第 5 行的 **Button** 块中，将操作 URL 设置为：

    ```liquid theme={null}
    {{cart_url}}
    ```

    <Frame caption="未添加样式的购物车遗弃基础电子邮件模板完成版">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/finished-template-abandoned-cart-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=a46cb86b4725c27c360b9f7cd96ab305" width="2968" height="2124" data-path="images/email/finished-template-abandoned-cart-tags.png" />
    </Frame>
  </Step>

  <Step title="测试和预览模板">
    使用 **Test & preview** 按钮向自己发送测试邮件。

    * 确保 Tags 已设置在您的电子邮件 Subscription 上。

    <Frame caption="带有 Tags 的预览邮件">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/test-email-with-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=307a846a3fec6676658ac4c653590110" width="2968" height="2124" data-path="images/email/test-email-with-tags.png" />
    </Frame>
  </Step>

  <Step title="设置模板样式">
    <Check>成功！现在您可以为模板应用自己的样式。请参阅[使用拖放设计电子邮件](./design-emails-with-drag-and-drop)。</Check>
  </Step>
</Steps>

### 推送模板

推送通知的空间有限，因此显示一个商品并提及总数量。

**消息字段：**

使用[条件语句](./using-liquid-syntax#if-elsif-else)显示商品和数量，并确保语法正确。

```liquid Liquid theme={null}
{% assign item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

**图片字段：**

```liquid Liquid theme={null}
{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

**启动 URL 字段：**

```liquid theme={null}
{{cart_url | default: "https://yourdomain.com/cart"}}
```

<Frame caption="使用 Test & preview 预览推送模板个性化">
  <img src="https://mintcdn.com/onesignal/Up-pAJT_jbhthm6E/images/push/preview-push-template-personalization-with-test-preview.png?fit=max&auto=format&n=Up-pAJT_jbhthm6E&q=85&s=97db90a05acdf4ed30f54a76b1d63b98" width="2880" height="2036" data-path="images/push/preview-push-template-personalization-with-test-preview.png" />
</Frame>

<Check>成功！您现在可以创建更多模板并在[购物车遗弃 Journey](./abandoned-cart) 中使用它们。</Check>

***

## 示例：使用数据标签个性化应用内消息

此示例显示了一个使用数据标签个性化的奖励应用内消息。该应用内消息将数据标签值替换到多种块类型中。

在配置的消息中：

* **文本块** — 显示完成的等级和该等级的奖励
* **图像块** — 显示该奖励对应的图像，并提供默认图像作为备用
* **按钮 2 文本** — 显示奖励值，默认值为 `100`
* **背景图像** — 从数据标签值设置

<Frame caption="在文本、图像和按钮块中配置了数据标签替换的应用内消息编辑器">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b697ab5-config1.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=c40e541c296b138a7f04ac561b3b0c64" alt="" width="872" height="968" data-path="images/docs/b697ab5-config1.png" />
</Frame>

消息在会话开始时使用用户当前的数据标签值进行渲染：

<Frame caption="向用户显示的应用内消息，其中包含从数据标签中替换的值">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/973f097-JustTheIAMTagSub.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=0626ef7b31dfbfece633e74b072fbff5" style={{ width:"100%" }} width="338" height="607" data-path="images/docs/973f097-JustTheIAMTagSub.png" />
</Frame>

<Note>
  有关支持的块、属性和时机规则，请参阅上方[渠道支持](#渠道支持)中的**应用内消息**选项卡。以下是需要再次强调的两点：

  * **数据标签必须在用户开始新的应用会话之前设置。** 在会话中更新的数据标签不会在该会话中显示的应用内消息中渲染。
  * **数据标签替换在"发送测试消息"测试发送中不起作用。** 从真实会话触发消息以验证替换是否正常。
  * [属性替换](./using-liquid-syntax#property-include)在应用内消息中不受支持。
</Note>

***

## 相关页面

<Columns cols={2}>
  <Card title="消息个性化" href="./message-personalization" icon="sparkles">
    OneSignal 中所有个性化选项的概述，包括何时使用 Custom Events 与其他方法。
  </Card>

  <Card title="Tags" href="./add-user-data-tags" icon="tag">
    了解如何通过 SDK、API 或 CSV 导入为用户设置 Tags。
  </Card>

  <Card title="使用 Liquid 语法" href="./using-liquid-syntax" icon="droplet">
    完整的 Liquid 参考，包括过滤器、条件语句、循环和字符串操作。
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    创建和管理可在 Journeys 中使用的可复用消息模板。
  </Card>

  <Card title="购物车遗弃教程" href="./abandoned-cart" icon="cart-shopping">
    使用 Tags 和属性构建购物车遗弃 Journey。
  </Card>
</Columns>

<Info>
  需要帮助？

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

  请包含以下信息：

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

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

***