Переменные и функции Altcraft

Данные профиля

Описание	Переменная
Email-адрес	{lead.email}
Список телефонов	{lead.phones}
Имя	{lead._fname}
Фамилия	{lead._lname}
Дата рождения	{lead._bdate}
Пол	{lead._sex}
Дата регистрации	{lead._regdate}
IP-адрес регистрации	{lead._regip}
Город регистрации	{lead._regcity}
Страна регистрации	{lead._regcountry}
URL-адрес регистрации	{lead._regurl}
IP-адрес	{lead._ip}
Город	{lead._city}
Страна	{lead._country}
Регион	{lead._region}
Индекс	{lead._postal_code}
Временная зона	{lead._tz}
Поставщик	{lead._vendor}
Идентификатор профиля	{lead._id}
XXM-хеш	{lead._xxm}
XX-хеш	{lead._xxh}
MD5-хеш	{lead._md5}
* Дополнительное поле	{lead.название_поля}

Подписки

Переменные подписок содержат данные по конкретной подписке и по используемому каналу отправки. Например, с её помощью не получится передать номер телефона при отправке по email.

Описание	Переменная
Email-адрес подписки	{subscription.email}
Домен email-адреса	{subscription.email_domain}
Список email-адресов подписки	{subscription.emails}
Телефон подписки	{subscription.phone}
Список телефонов подписки	{subscription.phones}
Список push-подписок	{subscription.pushes}
MD5-хеш email-адреса	{subscription.email_md5}
MD5-хеш телефона	{subscription.phone_md5}
Hash подписки	{subscription.hash_id}
Основное поле подписки	{subscription_field("channel" "field_name" resource_id)} channel — строка с указанием на канал ("email") field_name — имя поля для вставки ("domain") resource — идентификатор ресурса (10)

Функция subscription_field позволяет вставлять поля из подписок, независимо от того, какой канал используется в текущем сообщении. Например, если у профиля есть SMS-подписка, вы можете подставить его телефон в email версию сообщения:

{subscription_field("sms" "phone") 1}

Доступные поля для подстановки:

Канал	Поле	Описание
email	email	Email-адрес подписки
	domain	Домен email-адреса подписки
	domain_group	Доменная группа
	md5	MD5-хеш email-адреса
sms	phone	Телефон подписки
	md5	MD5-хеш телефона
push	subscription_id	Идентификатор push-подписки
	bundle_id	Идентификатор приложения для iOS APNs
	provider	Push провайдер
telegram_bot/telegram_group	id	ID чата

подсказка

Аналогично в шаблон можно подставлять данные из подписок пользовательских каналов. Поля основных каналов соответствуют sid полей, которые вы указываете при создании канала.

Кроме того, функция subscription_field позволяет обращаться к дополнительным полям подписки, созданным в настройках канала ресурса. Укажите имя дополнительного поля в качестве field_name:

{subscription_field("email" "custom_field_name")}

UTM

Если у профиля в его карточке есть UTM, то их можно подставить в шаблон сообщения.

Описание	Переменная
UTM-метка о рассылке	{lead._utm_campaign}
UMT-метка об источнике трафика	{lead._utm_source}
UMT-метка о типе контента	{lead._utm_medium}
UMT-метка о содержании контента	{lead._utm_content}
UMT-метка о ключевых словах	{lead._utm_term}

Внешний JSON

Внешний JSON-контент — это один из способов создавать динамические сообщения и автоматизировать работу. С его помощью в сообщение добавляется информация, генерируемая на вашем сервере точно в момент отправки каждого сообщения.

Подробнее о том, как работает внешний JSON можно прочесть в статье «Использование JSON-контента в сообщениях».

В тексте сообщения JSON-контент представлен переменными типа {json.variable}. Типы данных list и 'object' поддерживают циклы, для типа object также доступно обращение к элементам по ключу {json.object.key_name}.

Маркет

Чтобы использовать информацию о заказах и товарах в рассылках, вы можете добавить переменные маркета в шаблон сообщения. Более подробно использование таких переменных описано в статье "Использование переменных маркета в сообщениях".

Дата и время

Описание	Переменная	Пример
Форматированная дата	{format}	{format datenow "%Y-%m-%D %H:%M:%S timezone, %I am"} 2018-12-25 18:56:10 +03:00, 6 pm
Неформатированная дата	{datenow}	2018-12-25T18:56:10+0300
Смещение даты	{adddate()}	{adddate(datenow 0 0 3)} 2018-12-27T18:56:10+0300
Полный год	{yearlong}	2018
Год	{year}	18
Месяц	{month}	12
День	{day}	10
Часы в 24-часовом формате	{hours}	18
Часы в 12-часовом формате	{hours12}	06
«До полудня», «После полудня»	{ampm}	PM
Минуты	{minutes}	56
Секунды	{seconds}	10

Функции вывода

Описание	Переменная	Пример
Форматирование	format	{format 1000000000 ","} 1,000,000,000
Длина переменной	length	{length("abc")} 3
Массив значений	array	{array[1 "2" 3.3]} [1 2 3.3]
Случайный элемент массива	randomize	{randomize(array[1 2 3])} 1 Пример: в дополнительном поле профиля Favourite_genres хранится массив ["Детектив", "Юмор", "Фантастика"], выражение {randomize(lead.Favourite_genres)} выведет один случайный элемент, например "Детектив". Работает с полями Телефоны, Теги и Массив объектов, а также с массивами API-контента и внешнего JSON-контента.
Лимит массива	limit	{limit(array[1 2 3] 2)} [1 2]
Чётность числа	iseven	{iseven(2)} => true {iseven(3)} => false
Кодирование URL-адреса	urlencode	{urlencode(lead._regurl)} http:%2F%2Ftest.testdomain.com%2Fsomething Используется для кодирования недопустимых символов в URL параметрах.
Декодирование URL-адреса	urldecode	{urldecode(lead._regurl)} http://test.testdomain.com/something
Верхний регистр	uppercase	{uppercase("text")} TEXT
Первый символ в верхнем регистре	uppercasefirst	{uppercasefirst("john")} John
JSON-элемент без экранирования	jsonwithoutescaping	{jsonwithoutescaping(lead.example)} {"id": 1, "name": "test"} (без экранирования кавычек)

JSON-элемент без экранирования

Функция jsonwithoutescaping позволяет вставить в тело API-запроса значение поля профиля типа Объект или Массив объектов как готовый JSON, без экранирования внутренних кавычек.

{jsonwithoutescaping(lead.example)}

где lead.example — поле профиля, содержащее JSON-объект или массив объектов.

Зачем нужна. Если подставить такое поле обычным способом ({lead.example}), платформа экранирует кавычки внутри значения — в тело API-запроса попадёт невалидный JSON:

{"profile": "{\"id\": 1, \"name\": \"test\"}"}

С функцией jsonwithoutescaping значение передаётся как есть, и тело запроса остаётся корректным:

{"profile": {"id": 1, "name": "test"}}

к сведению

Функция проверяет, что переданное значение является валидным JSON. Если поле профиля содержит некорректный JSON, запрос с таким значением не будет сформирован корректно — проверьте данные в поле.

Чтобы вставить функцию, откройте редактор, нажмите на кнопку </> и выберите Функции вывода —> JSON-элемент без экранирования.

Шифрование

Шифрование переменных шаблона применяется когда необходимо передать данные вместе с кликом по URL на целевой сайт, но при этом данные не должны отражаться в журналах веб серверов или каким-то образом у пользователя. Например, в некоторых случаях данные предзаполнения форм достаточно закодировать в base58, чтобы на стороне сайта их раскодировать и подставить в форму.

Чтобы передавать контент шаблона и переменные в зашифрованном или хeшированном виде, в редакторе шаблонов предусмотрена функция crypt. Чтобы получить доступ к ней, нажмите на кнопку </> в редакторе шаблонов и выберите Шифрование.

{crypt(алгоритм поле ключ)}

Можно изменить кодировку или зашифровать данные по одному из этих алгоритмов:

• base58
• base64
• sha1
• sha256
• aes
• blowfish

Для sha1, sha256, aes и Blowfish необходимо указать ключ, который будет применяться на другой стороне для дешифровки значения.

Детали шифрования AES и Blowfish:

	AES	Blowfish
Вектор инициализации	Первые 16 байт строки	Первые 8 байт строки
Режим шифрования	CFB (Cipher Feedback)	CBC (Cipher Block Chaining)
Длина ключа	128 бит — 16 символов	64 бит — 8 символов
Padding	нулевой	нулевой

подсказка

Шифрование/дешифрование происходит через кодировку Base64URL.

Ниже приведены примеры синтаксиса для изменения кодировки и шифрования:

{crypt("base58" lead._fname)}
{crypt("base64" lead._lname)}
{crypt("sha256" lead.custom_field "encrypt_key")}
{crypt("sha1" lead._city "encrypt_key")}
{crypt("aes" lead._fname "key1234567891234")}
{crypt("blowfish" lead._fname "key12345")}

Алгоритм шифрования всегда заключается в кавычки. Если необходимо зашифровать строку текста, её нужно заключить в кавычки. Если число — кавычки не нужны:

{crypt("base58" "value")}
{crypt("base64" 42)}

Для хеширования доступны следующие алгоритмы. Для каждого можно использовать соль:

• md5 + соль
• xxh32 + соль
• xxh64 + соль

Синтаксис такой же, как для функций шифрования:

{crypt("md5" subscription.email "salt")}
{crypt("xxh32" loyalty.new2.promocode "salt")}
{crypt("xxh64" json.text "salt")}

Обратите внимание, что зашифрованные данные уже будут закодированы в base64.

Если вам необходимо зашифровать переменные внутри ссылки на форму, необходимо использовать функцию formcrypt:

{formcrypt(lead.email)}

При этом алгоритм шифрования для formcrypt не указывается.

Логические выражения

Использование логических выражений описано в отдельной статье. Для составления простого условия используется:

{if lead.age gte 18}
	Если 18 или старше.
{else}
	Если младше 18.
{end}

Фрагменты

Фрагменты сообщения

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

Для вызова фрагмента используйте {fragment.<короткое_имя_фрагмента>}.

Для вызова случайного фрагмента из диапазона: {randomfragment[fragment.name1 fragment.name2 fragment.name3]}.

Использование фрагментов более подробно описано в этой статье.

Фрагменты и части

В платформе также существует похожий функционал под названием части. Части отличаются от фрагментов тем, что настраиваются и используются в рамках одного письма. Чтобы начать работу с частями, добавьте в код шаблона переменную {part.example_part}. После этого внизу страницы появится вкладка «Контент», где вы сможете настроить части шаблона.

Подробнее о частях можно прочесть здесь.

Параметры

Параметры

Описание	Переменная
ID отправленного сообщения (SMID)	{send_message_id}
Токен ресурса	{resource_token}
ID шаблона	{msgid}
ID рассылки	{campid}
ID ресурса	{resid}
ID Базы данных (базы профилей)	{listid}
SUBID рассылки	{subid}
Имя ресурса	{resname}
Имя БД	{listname}
Тип сообщения	{msg_type}
URL ресурса	{resurl}
Домен URL ресурса	{resdomain}
Имя сообщения	{msgname}
Имя рассылки	{campname}
Имя отправителя SMS (SMS from name)	{from_name_sms}
ID сегмента	{segid}
Название сегмента	{segname}
Значение атрибута	{attribute_value("attribute")}, где вместо "attribute" — API-название атрибута

Служебные

Описание	Переменная
API-контент	{apicontent.field_name}
Отмена отправки сообщения	{cancel}

Трекинг

Описание	Переменная
Трекинг домен	{trkdomain}
Пиксель, фиксирующий открытие письма	{pixel}
Пиксель, фиксирующий чтение письма	{read}
Ссылка менеджера подписок	{preferences}
Ссылка отписки	{unsubscribe}
Ссылка глобальной отписки	{globalunsubscribe}
Добавление в стоп-список	{suppress}
Ссылка на веб-версию	{webversion}

Сценарий

Описание	Переменная
Название сценария	{workflow_name}
ID сценария	{workflow_id}
ID узла сценария	{node_id}
Тип узла сценария	{node_type}

События

Переменные событий позволяют работать с данными о действиях пользователей (просмотры страниц, добавления в корзину, покупки и др.), которые собираются через пиксели и цели.

События привязаны к контексту:

• В триггерных рассылках переменная содержит только события, относящиеся к конкретному триггеру, который запустил рассылку.
• В сценариях переменная содержит список всех событий, которые произошли с профилем с момента входа в сценарий.

к сведению

Эти переменные доступны только в триггерных рассылках и сценариях, которые запускаются по триггеру «Активация пикселя».

Переменные

Описание	Переменная	Примечания
Первое событие	{event.first}	Самое старое событие в текущем контексте
Последнее событие	{event.last}	Самое новое событие в текущем контексте
Все события	{event.all}	Полный список событий в порядке обратном поступлению, где в [0] самое последнее событие
Кол-во событий	{event.count}	Количество событий в очереди

Как использовать в шаблонах

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

{event.first.goal} // цель первого события
{event.last.value} // значение последнего события
{event.first.geo_city} // город из первого события
{event.last.utm_source} // источник последнего события
{event.first.browser} // браузер из первого события
{event.first.categories} // категории из первого события

Чтобы перебрать все события пользователя, используйте цикл:

{for $index $event = event.all}
            {if $event.goal equal "cart"}
                  {formatdate $event.date "%Y-%m-%D в %H:%M"} в корзину добавлены {$event.data.count}x {$event.data.product}.
              {end}
{else}
    <p>Нет событий...</p>
{end}

Примеры использования

Для триггерной рассылки после добавления в корзину:

Вы забыли товар: {event.first.data.product}
Цена: {event.first.data.price}
Купить: {event.first.data.link}

Для сегментации по геолокации:

В вашем городе {event.first.geo_city} проходит распродажа!

Для анализа эффективности рассылок:

Источник: {event.last.utm_source}
Рассылка: {event.last.utm_campaign}
Браузер: {event.last.browser}

Для вставки UTM-меток в ссылки:

<a href="https://site-example.ru/?utm_source={event.utm_source}&utm_medium={event.utm_medium}&utm_campaign={event.utm_campaign}&utm_content={event.utm_content}">
Перейти на сайт
</a>

Для использования в сценариях с узлом ожидания события:

Здравствуйте, {user.name}!

Вы недавно добавляли новый товар в корзину, но не оформили заказ.

Ваш товар ждёт вас:
{event.last.product_name} 

подсказка

Подробнее об элементе сценария «Ожидание события» можно прочесть здесь.

Параметры событий

Базовые поля событий

Параметр	Тип	Описание	Пример
id	string	Уникальный идентификатор события	{event.first.id}
type	string	Тип события платформы	{event.last.type}
date	DateTime	Время и дата события	{event.first.date}
test	bool	Признак тестового события	{event.last.test}

Геоданные

Параметр	Тип	Описание	Пример
geo_country	string	Страна (полное имя)	{event.first.geo_country}
geo_tld	string	Двухбуквенный код страны	{event.first.geo_tld}
geo_region	string	Регион	{event.first.geo_region}
geo_city	string	Город	{event.first.geo_city}
geo_address	string	Адрес	{event.first.geo_address}
geo_zip	string	Почтовый индекс	{event.first.geo_zip}
geo_time_zone	string	Часовой пояс	{event.first.geo_time_zone}
geo_lat	float	Широта	{event.first.geo_lat}
geo_lon	float	Долгота	{event.first.geo_lon}

UTM-метки

Параметр	Тип	Описание	Пример
utm_source	string	Источник трафика	{event.first.utm_source}
utm_medium	string	Канал трафика	{event.first.utm_medium}
utm_campaign	string	Название рассылки	{event.first.utm_campaign}
utm_content	string	Идентификатор контента	{event.first.utm_content}
utm_term	string	Ключевое слово	{event.first.utm_term}
utm_keyword	string	Ключевое слово (альтернативное)	{event.first.utm_keyword}

Событие пикселя (Pixel: goal)

Параметр	Тип	Описание	Пример
pixel_id	int	Идентификатор пикселя	{event.first.pixel_id}
goal	string	Название цели	{event.first.goal}
value	float	Значение цели	{event.first.value}
data	object	Произвольные данные цели (передаются в объекте pixel_data)	{event.first.data.order_id}
browser	string	Браузер пользователя	{event.first.browser}
user_agent	string	User-Agent браузера	{event.first.user_agent}
accept_language	string	Язык браузера	{event.first.accept_language}
count_items	int	Количество элементов	{event.first.count_items}
categories	string[]	Массив категорий	{event.first.categories}
send_message_id	string	ID отправки сообщения	{event.first.send_message_id}

Событие API-вызова (API: api_call)

Параметр	Тип	Описание	Пример
content	object	Данные из API-вызова	{event.first.content.order_id}
custom_data	object	Пользовательские данные API	{event.first.custom_data.field_name}

Типы событий

Группа	Тип	Описание
Pixel	goal	Активация пикселя, цели (включая API)
API	api_call	API-вызов через start сценария или триггера

Примечание: Все поля разных типов событий доступны на одном уровне. Например, {event.last.content} обращается к полю content события API-вызова, если это текущее событие.

подсказка

В документации разработчика вы найдете полную техническую информацию о форматах данных и ограничениях. Это поможет точно настроить сбор данных через API и правильно использовать их в шаблонах.

Программы лояльности

При вставке переменных программ лояльностей через окно вставки в редакторе перед вами откроется контекстное меню, в котором вы сможете выбрать программу лояльности и тип баллов (а также лимит количества транзакций и период активации транзакций для последних двух переменных):

Описание	Переменная
Баланс баллов участника	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.balance}
Баланс активных баллов участника	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.active_balance}
Баланс неактивных баллов участника	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.inactive_balance}
Баланс с названием валюты	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.balance_named}
Баланс активных баллов с названием валюты	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.active_balance_named}
Баланс неактивных баллов с названием валюты	{loyalty_program.<ID_программы_лояльности>.points.<ID_баллов>.inactive_balance_named}
Список ближайших сгораний баллов (где x — лимит количества транзакций, а y — период активации транзакций)	{loyalty_expiration_points(<ID_программы_лояльности> "<ID_баллов>" x y "desc")}
Список ближайших активаций баллов (где x — лимит количества транзакций, а y — период активации транзакций)	{loyalty_activation_points(<ID_программы_лояльности> "<ID_баллов>" x y "acs")}

Экранирование

Функция escape позволяет использовать строки, которые содержат символы, похожие на синтаксис переменных платформы.

{escape "..."}

Всё содержимое внутри кавычек передаётся без изменений — платформа не пытается интерпретировать его как переменные или функции.

Примеры

https://example.example/abcd?some={escape "{lead.email}"}

В этом примере {lead.email} остаётся в виде текста и не заменяется на реальный email профиля:

https://example.example/abcd?some={lead.email}

Если вы используете escape внутри HTML-ссылки, добавьте атрибут no-track, чтобы ссылка не ломалась при трекинге:

<a href="https://example.com/link?query={escape "{lead.email}"}" title="Перейти по ссылке" no-track>Ссылка с экранированием</a>

Экранирование кавычек и слешей

Если внутри строки встречаются кавычки, их необходимо экранировать обратным слешем \". Сам обратный слеш передаётся как \\.

Экранирование кавычек:

{escape "Строка с \"кавычками\" внутри"}` = `Строка с "кавычками" внутри`

Экранирование слешей

{escape "Обратный слеш: \\\\"} = Обратный слеш: \\

Промокод

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

Ваш промокод :{loyalty.sale15.promocode}

emoji

Вы также можете вставить в ваши шаблоны сообщений emoji. Для этого выберите соответствующий пункт в меню переменных и нажмите на нужный emoji.

Связи профилей

Общая формула переменной:

{relation.[короткое_имя_связи].[direct для прямых или reverse для обратных].[имя_свойства].[count — количество, total — сумма, top — топ связей]}

Количество прямых связей со свойством profit:

{relation.managers_loyal.direct.profit.count}

Топ обратных связей со свойством profit. Используется цикл для вывода нескольких значений:

{for $index $item = relation.managers_loyal.reverse.profit.top}
{$item.lead._fname} {$item.lead._lname} ({$item.value} profit)
{else} There is no ‘profit’ for you :(
{end}

Сумма значения свойства profit для прямой связи:

{relation.managers_loyal.direct.profit.total}

Дополнительные функции редактора

Форматирование цен

Также предусмотрена фунция форматирования числовых данных, которая делит число на блоки по три цифры заданным разделителем.

Price 8.000 RUR

<p>Price {format json.price "."} RUR</p>

Чтобы вставить функцию, нажмите на кнопку </> в редакторе шаблонов и выберите Функции вывода —> Форматирование.

Смещение даты

Функция adddate(date, year, month, day) возращает значение даты после того, как добавит к ней определённый интервал.

<p>Event starts on {adddate(lead.notify_date 0 0 10)}</p>

adddate() может использоваться внутри функции format().

<p>Event starts on {format adddate(lead.notify_date 0 0 10) "%Y-%m-%D"}</p>

Чтобы вставить функцию, нажмите на кнопку </> в редакторе шаблонов и выберите Дата и время —> Смещение дат.

Одновременно форматировать и сместить дату можно при помощи функции:

{format adddate(datenow 0 0 3) "%Y-%m-%D"}

Форматирование даты

Данные типа "дата" имеют разное представление в разных странах. Для удобства подписчиков предусмотрена функция форматирования дат.

Например, для того, чтобы представить дату рождения подписчика в виде:

Дата рождения 02.11.1998

Используется такая функция:

<p>Дата рождения {format lead._bdate "%D.%m.%Y"}</p>

Одновременно форматировать и сместить дату можно при помощи функции:

{format adddate(datenow 0 0 3) "%Y-%m-%D"}

Все параметры форматирования даты:

# years
"%y": "06"
"%Y": "2006"
"yy": "06"
"YYYY": "2006"

# months
"%m": "01"
"MM": "01"
"%B": "January"
"month": "January"
"%ru_month": «январь»

# days
"%d": "2"
"%D": "02"
"DD": "_2"
"%A": "Monday"
"weekday": "Monday"

# hours
"%H": "15"
"%I": "3"
"hh": "15"
"hours": "15"
"twelve_h": "3"

# mins
"%M": "04"
"mm": "04"

# seconds
"%S": "05"
"ss": "05"

# am/pm indicator
"am": "pm"
"AM": "PM"
"%p": "pm"

# timezone
"tzone": "-07"
"timezone": "-07:00"
"%Z": "Z0700"

Чтобы вставить функцию, нажмите на кнопку </> в редакторе шаблонов и выберите Дата и время —> Форматированная дата.

к сведению

Если в шаблоне используется контент из внешнего JSON (переменная apicontent или динамический JSON-контент), платформа может преобразовать строки в формате RFC 3339 в дату и время.

Пример форматирования:

Режим	Формат
JSON	"date_time": "2023-02-21T11:10:35.141Z"
Шаблон	{format apicontent.date_time "%Y-%m-%d %H:%M:%S"}
Предпросмотр	2023-02-21 11:10:35