🌐EN🛠️ Developer Guide
User Guide

Velocity у повідомленнях

Velocity дає змогу використовувати дані контактів, параметри подій і дані зовнішніх джерел безпосередньо в шаблонах повідомлень. Ця стаття охоплює основні техніки — змінні, об'єкти, масиви, цикли та умови — на прикладі email-підтвердження замовлення, а також особливості використання Velocity в коротких каналах.

Усі директиви в HTML-коді email мають бути загорнуті в коментарі: <!--#if(...)-->, <!--#foreach(...)-->, <!--#end-->. У SMS, Mobile Push, Viber, Telegram і App Inbox директиви використовуються без коментарів.

Як Velocity читає дані

Усі дані в eSputnik передаються у форматі JSON — структурованого тексту з парами "ключ: значення":

{
  "firstName": "Олена",
  "discount": "15%",
  "deliveryMethod": "express"
}

Щоб підставити значення в повідомлення, достатньо поставити $ перед назвою ключа:

Вітаємо, $firstName! Ваша знижка: $discount.

Результат: Вітаємо, Олена! Ваша знижка: 15%.

Якщо дані вкладені — наприклад, товар всередині замовлення — використовується крапкова нотація або індекс масиву. Детальніше про це в наступних секціях.

Джерела даних у повідомленнях

У шаблонах повідомлень доступні три типи даних:

  • Поля контакту — доступні в будь-якому повідомленні, підтягуються з картки контакту в момент відправлення
  • Параметри події — доступні в тригерних повідомленнях, передаються через сценарій, який запустила подія
  • Зовнішні джерела — доступні, якщо до повідомлення підключено зовнішнє джерело даних, наприклад Google BigQuery, Google Таблиці або HTTP-джерело

Усі ці дані доступні через Velocity. Головна відмінність — не в синтаксисі, а в тому, звідки надходять дані, як вони структуровані і в якому контексті доступні.

Техніки роботи з даними

Цикл #foreach для масивів

Якщо параметр події містить масив — наприклад, список товарів у замовленні — використовуйте #foreach, щоб пройтися по всіх елементах незалежно від їх кількості.

В email:

<!--#foreach($item in $items)-->
  <p>$item.name — $item.cost грн</p>
<!--#end-->

У коротких каналах (без коментарів):

#foreach($item in $items)
  $item.name — $item.cost грн
#end

$foreach.count — лічильник ітерацій, починається з 1.

Умови

Використовуйте #if / #elseif / #else, щоб показувати або приховувати контент залежно від значення:

<!--#if($deliveryMethod == 'express')-->
  <p>Експрес-доставка: 1–2 дні.</p>
<!--#elseif($deliveryMethod == 'Standard')-->
  <p>Стандартна доставка: 3–5 днів.</p>
<!--#else-->
  <p>Уточніть терміни доставки у підтвердженні.</p>
<!--#end-->

Використовуйте #if, щоб приховати блок, якщо значення відсутнє:

<!--#if($!{discount})-->
  <p>Знижка: $discount грн</p>
<!--#end-->

Звернення до одного елемента масиву

Якщо потрібен лише перший елемент масиву без циклу, використовуйте індекс (нумерація з 0):

$items[0].name
$items[0].cost

Це доречно, якщо масив завжди містить рівно один елемент або потрібно посилатися лише на перший запис.

Захист від порожніх значень

$!{item.imageUrl}        ← нічого не виводити, якщо відсутнє
${item.name|'Товар'}     ← запасне значення

Уникайте голих $змінна в продакшн-повідомленнях — якщо значення відсутнє, контакт побачить сирий текст змінної.

Приклади

Email-підтвердження замовлення

Побудуємо email-підтвердження замовлення на основі такої події:

{
  "eventTypeKey": "OrderCreated",
  "keyValue": "380501234567",
  "params": {
    "phone": "380501234567",
    "externalOrderId": "12345679",
    "externalCustomerId": "AV13760",
    "totalCost": 680,
    "status": "INITIALIZED",
    "date": "2020-05-14T10:11:00+02:00",
    "currency": "UAH",
    "shipping": 50,
    "discount": 10,
    "deliveryMethod": "Standard",
    "paymentMethod": "MasterCard/Visa",
    "deliveryAddress": "First str. 1",
    "items": [
      {
        "externalItemId": "200600",
        "name": "Super Device",
        "category": "devices",
        "quantity": 2,
        "cost": 300,
        "url": "http://example.com/item/200600",
        "imageUrl": "http://example.com/item/200600/image.png",
        "description": "High quality"
      }
    ]
  }
}

Примітка: Щоб передати дані замовлення до системи, використайте Add orders або Generate event.

Лист складається з чотирьох блоків: вітання, деталі замовлення, список товарів і підсумок.

Блок 1: Вітання

Ім'я контакта підтягується з картки, номер замовлення — з події:

ПараметрЗмінна
Ім'я${firstName}
Номер замовлення$externalOrderId

Блок 2: Деталі замовлення

Параметри верхнього рівня підставляються напряму як змінні:

ПараметрЗмінна
Номер замовлення$externalOrderId
Ім'я та прізвище$firstName $lastName
Спосіб доставки$deliveryMethod
Адреса доставки$deliveryAddress
Спосіб оплати$paymentMethod

Блок 3: Список товарів

Параметр items — це масив, який може містити один або кілька товарів. Обгорніть блок товару циклом #foreach:

<!--#foreach($item in $items)-->
  ...
<!--#end-->

Всередині циклу звертайтеся до кожного поля через $item.<назваПоля>:

ПолеЗмінна
Назва товару$item.name
Артикул$item.externalItemId
Ціна$item.cost
Кількість$item.quantity
Зображення$item.imageUrl
Посилання$item.url

Щоб підставити зображення динамічно, відкрийте налаштування блоку Зображення і додайте:

  • $!item.imageUrl — шлях до картинки
  • $!item.url — посилання
  • $!item.name — альтернативний текст

Блок 4: Підсумок замовлення

Загальні значення підставляються напряму:

ПолеЗмінна
Загальна вартість$totalCost
Знижка$discount
Доставка$shipping

Щоб розрахувати суму товарів (cost × quantity), розмістіть перед блоком підсумку такий код. Директиви виконуються, але не виводяться — після цього блоку $total містить розраховане значення:

<!--#set($total=0)
#foreach($item in $items)
#set($total=$!total + $mathTool.mul($!item.cost, $!item.quantity))
#end
-->

Виведіть $total у рядку "Сума товарів".

Умовне відображення блоків за профілем контакту

За допомогою Velocity можна показувати різні блоки листа залежно від значення поля в профілі контакту. Наприклад, якщо в профілі збережено стать, чоловіки бачитимуть добірку товарів для чоловіків, жінки — для жінок, а контакти без заповненого значення — загальну добірку.

  1. Розмістіть у шаблоні три окремі структури з контентом для різних сегментів: жіноча добірка, чоловіча добірка, загальна добірка.
  1. Виділіть структуру з товарами для жінок і відкрийте редактор коду.
  1. Додайте до коду назву додаткового поля контакту та умовний оператор, який відповідає за показ цієї структури.

Загальний формат:

<!--#if($!parameterName == 'value1')-->

У цьому прикладі:

<!--#if($!personal.gender == 'F')-->
  1. Виділіть структуру з товарами для чоловіків. Код цієї структури буде показано в редакторі.
  2. Додайте умовний оператор у код цієї структури над тегом tr.

Загальний формат:

<!--#elseif($!parameterName == 'value2')-->

У цьому прикладі:

<!--#elseif($!personal.gender == 'M')-->
  1. Виділіть структуру із загальною добіркою.
  2. Додайте в код над тегом tr оператор:
<!--#else-->
  1. Додайте після закриваючого тега </tr> загальної структури оператор:
<!--#end-->

Перевірка значень у різному регістрі

Якщо значення в полі можуть зберігатися по-різному, наприклад M або m, F або f, використовуйте розширену перевірку:

#if($!personal.gender == 'm' || $!personal.gender == 'M')

Або коротше:

#if('m'.equalsIgnoreCase($!personal.gender))

Velocity у коротких каналах

У коротких каналах — Mobile Push, Viber, SMS, Telegram — директиви використовуються без HTML-коментарів:

#foreach($order in $!orderData)
  $!order.name — $!order.cost грн
#end

Якщо динамічна частина повідомлення може перевищити обмеження на довжину — замість циклу зверніться до одного елемента за індексом:

$!orderData[0].name
$!recommendationsData[0].name — $!recommendationsData[0].price грн

Перевірка шаблону

Перейдіть до Додаткові параметри → Налаштування динамічного контенту, вставте JSON з потрібними параметрами і натисніть Перегляд повідомлення.

Параметри можна скопіювати безпосередньо з будь-якої події замовлення: перейдіть до Тригери → Історія подій, клікніть на подію і скопіюйте її параметри. Це найпростіший спосіб перевірити назви полів, шляхи в масивах і умови перед відправленням.

Наступні кроки

Updated 10 days ago