# Liquid 模板

<YouTube id="A7l1_gK5yOA" playlabel="YouTube 视频：了解如何在 Customer Journey 中使用内容模板"/>

Liquid 模板通过实现复杂的逻辑，在常规[动态内容](/zh/product/personalization/dynamic-content/)使用的基础上，极大地扩展了 Pushwoosh 的个性化功能。

Pushwoosh 中的消息个性化基于[标签（用户数据）](/zh/product/audience-data-and-segmentation/user-data-tags/tags)。Pushwoosh 提供多种[默认标签](/zh/product/audience-data-and-segmentation/user-data-tags/tags#default-tags)和[自定义标签](/zh/product/audience-data-and-segmentation/user-data-tags/tags#custom-tags)。使用它们，您可以指定用户的名字、城市、购买历史等，以发送更具个性化的消息。例如：`Hi {{First_name}}, thanks for ordering {{item}}`。

Liquid 模板为动态内容添加了更多逻辑。例如，如果用户的订阅标签包含 "free"，您可以向他们发送一条消息：“领取您的 10% 折扣。”

根据用户的 ID、行为和偏好修改消息内容，是提高相关性并从您的营销活动中获得更佳效果的最有效方法。

## 语法

基于 [Shopify 的 Liquid](https://shopify.github.io/liquid/) 的内容模板使用[**标签**](#tags)、[**对象**](#objects)和[**过滤器**](#undefined)的组合来加载动态内容。内容模板允许您从模板内部访问某些变量并输出其数据，而无需了解数据本身的任何信息。

<Aside type="note">
要了解有关语法的更多信息，请参阅 [Liquid 文档](https://shopify.github.io/liquid/basics/introduction/)。
</Aside>

### 对象

`objects` 定义将向用户显示的内容。`objects` 应包含在双花括号中：`{{ }}`

例如，在个性化消息时，在其正文中发送 `{{Name}}` 以将用户的姓名添加到消息内容中。用户的姓名（Name 标签值）将替换用户将看到的消息中的 Liquid 对象。

<Tabs>
<TabItem label="输入">
```
Hi {{Name}}! We're glad you're back!
```
</TabItem>

<TabItem label="输出">
Hi Anna! We're glad you're back!
</TabItem>
</Tabs>

### 标签

`tags` 为模板创建逻辑和控制流。花括号百分号分隔符 `{%` 和 `%}` 及其包围的文本在模板呈现时不会产生任何可见输出。这使您可以分配变量并创建条件或循环，而无需向用户显示任何 Liquid 逻辑。

例如，使用 `if` 标签，您可以根据用户设备上设置的语言来改变消息的语言：

<Tabs>
  <TabItem label="输入">

```liquid
{% if Language == 'fr' %}
Salut!
{% else %}
Hello!
{% endif %}
````

  </TabItem>

  <TabItem label="输出 (fr)">
    Salut!
  </TabItem>

  <TabItem label="输出 (es)">
    Hello!
  </TabItem>
</Tabs>

### 标签运算符

<table data-header-hidden><thead><tr><th width="189.5" align="center">运算符</th><th>描述</th></tr></thead><tbody><tr><td align="center"><code>==</code></td><td>等于</td></tr><tr><td align="center"><code>!=</code></td><td>不等于</td></tr><tr><td align="center"><code>></code></td><td>大于</td></tr><tr><td align="center"><code>&#x3C;</code></td><td>小于</td></tr><tr><td align="center"><code>>=</code></td><td>大于或等于</td></tr><tr><td align="center"><code>&#x3C;=</code></td><td>小于或等于</td></tr><tr><td align="center"><code>or</code></td><td>逻辑或</td></tr><tr><td align="center"><code>and</code></td><td>逻辑与</td></tr><tr><td align="center"><code>contains</code></td><td>检查字符串或字符串数组中是否存在子字符串</td></tr></tbody></table>

<Aside type="note">
在具有多个 `and` 或 `or` 运算符的标签中，运算符按_从右到左_的顺序检查。您不能使用括号更改运算顺序——括号是 Liquid 中的无效字符，会导致您的标签无法工作。
</Aside>

### 过滤器

`filters` 修改 Liquid 对象或变量的输出。它们在双花括号 `{{ }}` 和变量赋值中使用，并由管道符 `|` 分隔。一个输出上可以使用多个过滤器，并从左到右应用。

<Tabs>
<TabItem label="输入">

```

{{ Name | capitalize | prepend:"Hello " }}

```

</TabItem>

<TabItem label="输出">

Hello Anna

</TabItem>
</Tabs>

## Liquid 模板用法

Liquid 模板可用于从 Control Panel 发送的消息和 [API 请求](/zh/developer/guides/personalization/liquid-templates#using-liquid-templates-in-messages-sent-via-api)。

在 Pushwoosh 中，Liquid 模板适用于任何渠道消息的所有内容字段：

*   推送通知
*   电子邮件

要将 Liquid 模板添加到您的消息中，请将其插入消息正文。您可以在处理[推送](/zh/product/customer-journey/journey-elements/#push)或[电子邮件](/zh/product/customer-journey/journey-elements/#email)元素时，直接从 Customer Journey Builder 界面执行此操作。

转到 **Customer Journey Builder** > **创建营销活动** > 将以下元素拖放到您的画布上：**基于受众的入口**、**推送**（或**电子邮件**）和**退出**。连接这些元素。然后单击**推送**图标，选择**自定义内容**，并插入您的文案。

要添加 Liquid 逻辑，请使用以下语法的标签值：

```liquid  
{% if TagName == 'value' %}  
  Content to send in this scenario  
{% else %}  
  Content to send otherwise  
{% endif %}
```
然后单击**应用**。

<video src="/personalization-liquid-templates-1.webm" title="Customer Journey Builder 界面，展示如何使用 if-else 条件向推送通知内容添加 Liquid 模板逻辑" autoplay loop muted playsinline />

模板变量（Pushwoosh 标签）不应包含任何空格，并且只能包含字母数字值和下划线，例如 `my_tag` 或 `myTag`，而不是 `My Tag`。

[了解有关 Journey 中 Liquid 模板的更多信息](/zh/product/customer-journey/journey-elements/dynamic-content-and-liquid-templates-in-journeys)

<Aside type="tip">
您还可以在 `/createMessage` 请求中使用 Liquid 语法来实现 Liquid 模板。为此，您需要开发团队的协助。请与他们分享[Liquid 模板指南](/zh/developer/guides/personalization/liquid-templates)以获取详细指导。
</Aside>

## 连接内容

连接内容是 Liquid 模板中的一项功能，允许您直接在电子邮件或推送通知消息中动态检索和使用来自外部来源（例如 Web 服务）的数据。此功能通过从指定 URL 获取 JSON 数据并将其保存到可在内容中使用的变量中，从而实现实时个性化。

#### 主要用例

-   **产品推荐**：显示为每个用户量身定制的个性化产品列表。
-   **促销代码**：插入由后端服务生成的唯一促销代码。

#### 前提条件

*   要使用连接内容，您必须拥有自己的后端服务，该服务根据 **User ID、HWID 或自定义标签**生成并提供所需的数据（例如，促销代码、产品推荐）。然后，Pushwoosh 在发送消息前会获取这些数据。

### 分步实施指南

<Aside type="caution" icon="setting" title="需要开发者协助">
您需要开发团队的帮助才能使用连接内容。请与他们分享本指南以开始使用。
</Aside>

#### 第 1 步：设置后端服务

后端服务应：

*   接受包含用户特定参数（例如 `userId`）的请求。连接内容支持 `UserID`、`HWID` 或您在项目中设置的任何自定义标签。
*   返回包含所需数据的 JSON 响应。然后，这些内容可以动态插入到消息中

<Aside type="note" title="工作原理">

后端服务充当数据提供者，响应带有用户特定信息的 HTTP 请求。

1.  Pushwoosh 向您的后端发送请求，将用户特定的标识符作为查询参数传递。
2.  您的后端处理请求并检索所请求的数据。
3.  您的后端返回一个 JSON 响应。
4.  在发送消息之前，Pushwoosh 从后端服务获取 JSON 响应，并在消息内容中动态使用返回的值（例如 `code`）。

**响应示例**

```
{ "code": "SPECIALOFFERFORUSER12345" }
```
</Aside>

#### 第 2 步：在 Pushwoosh 中创建带有连接内容的预设

1.  在[推送](/zh/product/content/push-presets/)或[电子邮件内容编辑器](/zh/product/content/email-content/drag-and-drop-email-editor/)中，将连接内容语法插入消息字段。

**示例**

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :save result %}  
```
**语法分解**
|  |  |
| ----- | ----- |
| `connected_content` | 从指定的后端 URL 获取 JSON 数据。 |
| `http://your-backend-url.com` | 以 JSON 格式返回所需数据的后端端点。 |
| `userId={{ ${userid} }}` | 将用户 ID 传递给后端的动态查询参数。 |
| `:save result` | 将获取的 JSON 响应存储在 result 变量中，以供在 Liquid 模板中使用 |

![插入连接内容语法](/connectedcontent.webp)

**身份验证（可选）**

如果您的后端服务需要身份验证，您可以在连接内容请求中包含 API 密钥或令牌，以确保安全访问。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }}&auth=YOUR_API_KEY :save result %}  
```

您还可以使用可选的 `:headers` 参数（一个包含标头名称和值的 JSON 对象）将身份验证（或任何其他）数据作为 HTTP 标头发送。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :headers {"Authorization": "Bearer YOUR_TOKEN", "X-Api-Key": "YOUR_API_KEY"} :save result %}  
```
|  |  |
| ----- | ----- |
| `:headers {...}` | 随请求发送的 HTTP 标头 JSON 对象，例如 `Authorization: Bearer <token>`。 |

<Aside type="caution" title="仅限静态值">
`${}` 个性化变量仅在 URL 内部有效。`:headers` 内部的值是静态的，不会被插值。
</Aside>

**在连接内容中使用标签**

要包含自定义标签，请将它们作为查询参数插入到**连接内容**请求中 (`{{ tag_name }}`)。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }}{{ Language }} :save result %} 
```

2.  接下来，添加包含**检索到的数据**的消息文本，如下所示：

```

Hey, {{userid}}, grab your personal promo code - {{result.code}} 
```

![添加包含**检索到的数据**的消息文本](/connectedcontent-1.webp)

3.  在最终确定消息内容并配置预设设置后，保存它以便在营销活动中重复使用。

<video src="/connectedcontent-2.webm" title="发送带有连接内容的消息" autoplay loop muted playsinline />

#### 第 3 步：使用配置的预设发送消息

使用[一次性推送](/zh/product/messaging-channels/push-notifications/send-push-notifications/one-time-push/#how-to-send-a-push-notification-using-the-one-time-push-form)或[电子邮件表单](/zh/product/messaging-channels/emails/sending-emails/send-one-time-emails/)或 [Customer Journey](/zh/product/customer-journey/pushwoosh-journey-overview/) 发送带有此预设的消息。

<Aside type="caution" title="重要">
如果服务返回的状态不是 HTTP 200 OK，则不会发送电子邮件或推送通知。这确保了只有在成功检索到必要数据时，您的通信才会发出。
</Aside>