Тестування та відлагодження Velocity

Попередній перегляд динамічного контенту

Перед відправленням перегляньте, як Velocity-змінні підставляються з реальними даними безпосередньо в редакторі повідомлень.

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

Введіть значення параметрів у форматі JSON і натисніть Перегляд повідомлення.

Якщо у Velocity-коді є помилки, замість повідомлення буде показано їх опис.

Тестування з реальними даними замовлення

Якщо повідомлення тригерне, можна скопіювати реальні параметри події безпосередньо з інтерфейсу.

Перейдіть до Тригери → Історія подій, клікніть на подію і скопіюйте її параметри.

Вставте скопійовані параметри в поле Налаштування динамічного контенту і натисніть Перегляд повідомлення.

Це найпростіший спосіб перевірити назви полів, шляхи в масивах і умови перед відправленням.

Перевірка доступного контексту змінних

Перш ніж відлагоджувати вираз, перевірте, яке джерело даних реально доступне в поточному контексті.

Джерело	Де доступне	Типовий патерн доступу
Поля контакту	Повідомлення, сценарії, сегменти	`${firstName}`, `${email}`
Параметри події	Лише всередині сценарію, запущеного цією подією	`$deliveryMethod`, `$items[0].name`
Дані зовнішнього джерела	Повідомлення або сценарії, де це джерело підключено	Залежить від джерела
Дані відповіді вебхука	Після виклику блоку Вебхук у сценарії	Залежить від структури відповіді

Якщо значення не підставляється — перевірте, чи доступне очікуване джерело в поточному контексті.

Правила чутливості до регістру

Тип даних	Чутливість до регістру
Назви полів контакту	Нечутливі: `${firstName}` = `${FIRSTNAME}`
Назви параметрів події	Чутливі: `$deliveryMethod` ≠ `$DeliveryMethod`
Назви полів зовнішніх джерел	Чутливі: мають точно відповідати заголовкам колонок або ключам JSON

Змінна не підставляється

Симптом: у повідомленні замість значення виводиться буквальний текст $firstName або $deliveryMethod.

Причини та виправлення:

Причина	Виправлення
Назва змінної не збігається з назвою поля або параметра	Перевірте написання і регістр за списком полів контакту або параметрами події
Значення відсутнє, використовується синтаксис `$var`	Використовуйте `$!{var}` або `${var\|'запасне значення'}`
Параметр події недоступний у цьому контексті	Перевірте, що повідомлення надсилається через правильний сценарій
Зовнішнє джерело даних не підключено до повідомлення	Підключіть джерело даних у налаштуваннях повідомлення

Проблеми з відображенням директив у email

Симптом: вміст #foreach або #if відображається як сирий текст, або верстка листа ламається.

Причина: директиви в HTML-коді email мають бути загорнуті в коментарі. Без обгортки email-клієнт сприймає їх як некоректну розмітку.

Виправлення: загорніть усі директиви в HTML-коментарі:

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

<!--#if($deliveryMethod == 'express')-->
  <p>Експрес-доставка: 1–2 дні.</p>
<!--#end-->

Це правило стосується лише email. У SMS, Mobile Push, Viber, Telegram і App Inbox директиви використовуються без коментарів.

Типові помилки з масивами та вкладеними об'єктами

Вихід за межі масиву

$items[3].name    ← помилка, якщо в масиві менше 4 елементів

Використовуйте #foreach, якщо розмір масиву заздалегідь невідомий, або перевірте розмір перед зверненням:

#if($items.size() > 3)
  $items[3].name
#end

Відсутній #end

Кожен #if і #foreach має закриватися директивою #end. Відсутній #end ламає рендеринг усього, що стоїть після нього в шаблоні.

<!--#if($deliveryMethod == 'express')-->
  <p>Експрес-доставка.</p>
<!--#end-->    ← обов'язково

Невірний шлях до вкладеного значення

$lastProductAdded.externalItemId    ← працює, якщо lastProductAdded — об'єкт
$lastProductAdded[0].externalItemId ← використовуйте, якщо lastProductAdded — масив

Якщо вкладене значення не підставляється — перевірте, чи є батьківський елемент об'єктом або масивом у тілі події.

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

Довідник Velocity — повний довідник синтаксису
Velocity у повідомленнях — практичні приклади для шаблонів
Velocity у сценаріях — практичні приклади для сценаріїв

Updated about 1 hour ago