# Шаблоны Liquid

<YouTube id="A7l1_gK5yOA" playlabel="Видео на YouTube: Узнайте, как использовать шаблоны контента в Customer Journey"/>


Шаблоны Liquid значительно расширяют возможности персонализации Pushwoosh, позволяя реализовывать сложную логику в дополнение к обычному использованию[ динамического контента](/ru/product/personalization/dynamic-content/).

Персонализация сообщений в Pushwoosh основана на [тегах (данных пользователя)](/ru/product/audience-data-and-segmentation/user-data-tags/tags). Pushwoosh предлагает множество [тегов по умолчанию](/ru/product/audience-data-and-segmentation/user-data-tags/tags#default-tags) и [пользовательских тегов](/ru/product/audience-data-and-segmentation/user-data-tags/tags#custom-tags). С их помощью вы можете указать имя пользователя, город, историю покупок и т. д., чтобы отправить более персонализированное сообщение. Например: `Привет, {{First_name}}, спасибо за заказ {{item}}`.

Шаблоны Liquid добавляют больше логики в динамический контент. Например, если тег подписки пользователя содержит "free", вы можете отправить ему сообщение: "Получите скидку 10%".

Изменение содержания сообщения в соответствии с ID, поведением и предпочтениями пользователей — это самый эффективный способ повысить релевантность и получить более впечатляющие результаты от ваших маркетинговых кампаний.

## Синтаксис

Шаблоны контента, основанные на [Liquid от Shopify](https://shopify.github.io/liquid/), используют комбинацию [**тегов**](#tags), [**объектов**](#objects) и [**фильтров**](#undefined) для загрузки динамического контента. Шаблоны контента позволяют вам получать доступ к определенным переменным из шаблона и выводить их данные, не зная ничего о самих данных.

<Aside type="note">
Чтобы узнать больше о синтаксисе, обратитесь к [документации Liquid](https://shopify.github.io/liquid/basics/introduction/).
</Aside>

### Объекты

`Объекты` определяют контент, который будет показан пользователю. `Объекты` должны быть заключены в двойные фигурные скобки: `{{ }}`

Например, при персонализации сообщения отправьте `{{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>

### Теги

`Теги` создают логику и управляют потоком выполнения для шаблонов. Разделители в виде фигурных скобок и процентов `{%` и `%}` и текст, который они окружают, не создают видимого вывода при рендеринге шаблона. Это позволяет вам присваивать переменные и создавать условия или циклы, не показывая пользователю никакой логики 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>

### Фильтры

`Фильтры` изменяют вывод объекта или переменной Liquid. Они используются внутри двойных фигурных скобок `{{ }}` и при присваивании переменных и разделяются символом вертикальной черты `|`. К одному выводу можно применить несколько фильтров, и они применяются слева направо.


<Tabs>
<TabItem label="Входные данные">

```

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

```

</TabItem>

<TabItem label="Результат">

Hello Anna

</TabItem>
</Tabs>



## Использование шаблонов Liquid

Шаблоны Liquid доступны как для сообщений, отправляемых из Панели управления, так и для [API-запросов](/ru/developer/guides/personalization/liquid-templates#using-liquid-templates-in-messages-sent-via-api).

В Pushwoosh шаблоны Liquid применимы ко всем полям контента любого сообщения канала:

* Push-уведомления
* Email-сообщения

Чтобы добавить шаблон Liquid в ваше сообщение, вставьте его в тело сообщения. Вы можете сделать это при работе с элементами [push](/ru/product/customer-journey/journey-elements/#push) или [email](/ru/product/customer-journey/journey-elements/#email) прямо из интерфейса конструктора Customer Journey.


Перейдите в **Конструктор Customer Journey** > **Создать кампанию** > перетащите следующие элементы на холст: **Вход на основе аудитории**, **Push** (или **Email**) и **Выход**. Соедините элементы. Затем нажмите на иконку **Push**, выберите **Пользовательский контент** и вставьте ваш текст.


Чтобы добавить логику Liquid, используйте значения тегов со следующим синтаксисом:  

```liquid  
{% if TagName == 'value' %}  
  Контент для отправки в этом сценарии  
{% else %}  
  Контент для отправки в противном случае  
{% endif %}
```
Затем нажмите **Применить**.

<video src="/personalization-liquid-templates-1.webm" title="Интерфейс конструктора Customer Journey, показывающий, как добавить логику шаблона Liquid с условиями if-else в контент push-уведомления" autoplay loop muted playsinline />

Переменные шаблона (теги Pushwoosh) не должны содержать пробелов и должны состоять только из буквенно-цифровых символов и знаков подчеркивания, например, `my_tag` или `myTag` вместо `My Tag`.

[Узнайте больше о шаблонах Liquid в Journey](/ru/product/customer-journey/journey-elements/dynamic-content-and-liquid-templates-in-journeys)

<Aside type="tip">
 Вы также можете использовать синтаксис Liquid в запросах `/createMessage` для реализации шаблонов Liquid. Для этого вам понадобится помощь вашей команды разработчиков. Поделитесь с ними [руководством по шаблонам Liquid](/ru/developer/guides/personalization/liquid-templates) для получения подробных инструкций.
</Aside>

## Подключенный контент

Подключенный контент — это функция в шаблонах Liquid, которая позволяет динамически извлекать и использовать данные из внешнего источника, такого как веб-сервис, непосредственно в ваших email-сообщениях или push-уведомлениях. Эта функция обеспечивает персонализацию в реальном времени, извлекая JSON-данные по указанному URL и сохраняя их в переменную, которую можно использовать в вашем контенте. 

#### Основные сценарии использования

- **Рекомендации по продуктам**: отображение персонализированных списков продуктов, адаптированных для каждого пользователя.

- **Промокоды**: вставка уникальных промокодов, сгенерированных бэкенд-сервисом.

#### Предварительные условия

* Чтобы использовать подключенный контент, у вас должен быть собственный бэкенд-сервис, который генерирует и предоставляет необходимые данные (например, промокоды, рекомендации по продуктам) на основе **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. В [редакторе контента Push](/ru/product/content/push-presets/) или [Email](/ru/product/content/email-content/drag-and-drop-email-editor/) вставьте синтаксис подключенного контента в поле сообщения.

**Пример** 

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :save result %}  
```
**Разбор синтаксиса**
|  |  |
| ----- | ----- |
| `connected_content` | Извлекает JSON-данные с указанного URL бэкенда. |
|    `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 %}  
```

Вы также можете отправлять данные аутентификации (или любые другие данные) в виде HTTP-заголовков, используя необязательный параметр `:headers` — JSON-объект с именами и значениями заголовков.

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :headers {"Authorization": "Bearer YOUR_TOKEN", "X-Api-Key": "YOUR_API_KEY"} :save result %}  
```
|  |  |
| ----- | ----- |
| `:headers {...}` | JSON-объект HTTP-заголовков, отправляемых с запросом, например, `Authorization: Bearer <token>`. |

<Aside type="caution" title="Только статические значения">
Переменные персонализации `${}` работают только внутри URL. Значения внутри `:headers` являются статическими и не интерполируются.
</Aside>

<Aside type="danger" title="Не храните учетные данные в URL">
Предпочитайте `:headers` параметру запроса URL (например, `&auth=YOUR_API_KEY`) для API-ключей и токенов: если запрос не удастся, URL запроса записывается в логи, раскрывая размещенный там ключ. Значения внутри `:headers` никогда не логируются.

Подключенный контент также требует, чтобы для вашей учетной записи были включены шаблоны контента Liquid. Если они не включены, весь тег `connected_content` — включая любой ключ внутри него — отправляется каждому получателю как обычный текст вместо рендеринга. Свяжитесь со [службой поддержки Pushwoosh](https://help.pushwoosh.com/hc/en-us/requests/new), если вы не уверены, включена ли эта функция для вашей учетной записи.
</Aside>

**Использование тегов в подключенном контенте**

Чтобы включить пользовательские теги, вставьте их в качестве параметров запроса в запрос **подключенного контента** (`{{ tag_name }}`).

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

2. Затем добавьте текст сообщения, включающий **полученные данные**, например:

```

Привет, {{userid}}, получи свой личный промокод - {{result.code}} 
```

![Добавьте текст сообщения с полученными данными](/connectedcontent-1.webp)

3. После завершения работы с контентом сообщения и настройки параметров пресета сохраните его для повторного использования в кампаниях.

<video src="/connectedcontent-2.webm" title="Отправка сообщения с подключенным контентом" autoplay loop muted playsinline />

#### Шаг 3. Отправьте сообщение, используя настроенный пресет 

Отправьте сообщение с этим пресетом, используя [форму одноразовой отправки push-уведомления](/ru/product/messaging-channels/push-notifications/send-push-notifications/one-time-push/#how-to-send-a-push-notification-using-the-one-time-push-form) или [email-сообщения](/ru/product/messaging-channels/emails/sending-emails/send-one-time-emails/) или [customer journey](/ru/product/customer-journey/pushwoosh-journey-overview/). 

<Aside type="caution" title="Важно">
Если сервис вернет статус, отличный от HTTP 200 OK, email-сообщение или push-уведомление не будет отправлено. Это гарантирует, что ваше сообщение будет отправлено только в том случае, если необходимые данные будут успешно получены.
</Aside>