🌐EN🛠️ Developer Guide
User Guide
Start typing to search…

Використання препроцесору

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

За допомогою препроцесора можна:

  • підставляти персональні рекомендації;
  • змінювати порядок блоків у повідомленні;
  • формувати випадкові вибірки товарів;
  • показувати актуальні пропозиції для різних сегментів користувачів.

Препроцесор не потребує інтеграції з сторонніми сервісами або регулярного оновлення додаткових полів контакту. Його можна використовувати як у масових розсилках, так і в тригерних повідомленнях.

Персоналізація на основі препроцесора підтримується не лише в email-повідомленнях, але й у SMS.

Типи препроцесора

Для публічного використання доступні два типи препроцесора:

  • Key 
  • Random

Key-препроцесор

Key-препроцесор вибирає з масиву даних структуру за заданим ключем (email або номер телефону) і передає її до шаблону повідомлення перед відправленням.

Такий підхід дозволяє сформувати індивідуальний набір рекомендацій для кожного контакту.

Приклад файлу:

{
  "[email protected]": [
    {
      "name": "book",
      "price": "11"
    },
    {
      "name": "ball",
      "price": "22"
    },
    {
      "name": "game",
      "price": "33"
    }
  ],
  "[email protected]": [
    {
      "name": "food",
      "price": "44"
    },
    {
      "name": "drink",
      "price": "55"
    }
  ]
}

Ключем у структурі є адреса отримувача. Для кожного ключа передається окремий масив даних, який використовується під час формування повідомлення.

Random-препроцесор

Random-препроцесор вибирає випадкову кількість елементів із підготовленого набору даних і передає їх у повідомлення.

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

У той самий час у вас 100 товарів, однакових за привабливістю та якістю. Можна завантажити їх усі в Random-препроцесор і в кожному листі показувати будь-які випадкові три моделі. Тоді товари продаватимуться рівномірно і успішність кожної позиції можна буде перевірити за кількістю продажів/переходів, які вони принесли.

Приклад файлу:

{
  "recommendations": [
    {
      "name": "rnd1",
      "price": "11"
    },
    {
      "name": "rnd2",
      "price": "22"
    },
    {
      "name": "rnd3",
      "price": "33"
    }
  ]
}

Адреса отримувача в цьому випадку не використовується. Дані вибираються випадково з одного масиву.

Кількість елементів, яку буде вирахувано, можна вказати в листі двома способами:

  1. Вказати змінну у велосіті-коді: $forEachLimit=2;
  2. Не використовувати цикл у велосіті, натомість звертатися до елементів за індексом: $data.get('recommendations').get(0) — тоді буде обчислено максимальний індекс і вирахувано відповідну кількість елементів.

Принцип роботи препроцесора

Для коректної роботи препроцесора необхідно:

  1. Підготувати файл із даними у форматі та структурі, що підтримуються системою.
  2. Додати Velocity-код у повідомлення для формування та підстановки динамічного контенту.

Файл містить динамічні дані, а Velocity-код визначає логіку їх обробки та відображення під час відправлення.

Препроцесор типу Key дозволяє завантажити персональну добірку товарів для кожного клієнта, тому структура даних має виглядати так:

{
  "[email protected]": [
    {},
    {}
  ],
  "[email protected]": [
    {},
    {},
    {}
  ],
  "[email protected]": [
    {},
    {}
  ]
}

 де [email protected], [email protected], [email protected] — емейл-адреса (або номер телефону) одержувача, кожному з яких відповідає масив даних для підстановки в лист.

Препроцесор типу Random дозволяє вибрати з добірки випадкові структури для підстановки їх у листи для одержувачів. Структура файлу для нього має такий вигляд:

{
  "[email protected]": [
    {},
    {},
    {},
    {},
    {},
    {}
  ]
}

у цьому випадку емейл можна вказати будь-який — він не має значення; а єдиний масив містить усю добірку даних для випадкового вибору.

Під час відправлення листа препроцесор визначає, яку саме структуру даних передати до листа. Якщо використовується тип Key — передається структура, задана для конкретного отримувача; якщо використовується тип Random — структура визначається випадково. Результуючий масив даних можна використовувати в листі за допомогою спеціальних інструкцій, заданих у вигляді коду. Ці інструкції містять умовні оператори й цикли, що дозволяє в досить гнучкий спосіб відобразити динамічний контент у тілі листа.

Завантаження файлу для препроцесора

Існує два способи передання файлу з даними до системи.

Варіант 1. Завантаження через API

Процес складається з таких кроків:

  1. Завантажте файл із динамічним контентом у форматі JSON для підстановки в повідомлення за допомогою Velocity (API-метод POST Upload file for preprocessor). У відповіді повертається ідентифікатор файлу, який надалі використовується для його оновлення.
  2. Оновіть раніше завантажений файл (API-метод POST Update file for preprocessor).
  3. Отримайте статус файлу, який завантажується або вже завантажено (API-метод GET Get preprocessor file status).
  4. Виберіть файл у листі та використовуйте підстановку контенту під час розсилок або тригерних одинjчних відправлень (IMCallout — через сценарій або метод Send prepared message).

Після оновлення файлу нові дані автоматично використовуються без зміни повідомлення або сценарію.

Варіант 2. Завантаження через налаштування акаунта

Щоб завантажити файл через особистий кабінет:

  1. Перейдіть до налаштувань акаунту, виберіть вкладку Препроцесор і натисніть кнопку Завантажити файл.
  1. Виберіть тип препроцесора. Для прикладу виберемо тип Key (налаштування препроцесора з типом Random відбуватиметься аналогічно).
  1. Встановіть термін зберігання файлу у днях. За замовчуванням це значення дорівнює 10 дням, максимум — 60 дням. Після закінчення цього часу файл буде видалено з системи та зі списку доступних файлів.
  2. Перетягніть файл у цю область або клікніть для завантаження з комп'ютера. Файл має бути у форматі json, zip або tar.gz. Максимальний розмір файлу — 50 Гб.
  1. Натисніть Завантажити.

Після успішного завантаження система надішле повідомлення в інтерфейсі та на email.

Створення повідомлення з використанням препроцесора

Для роботи з динамічними даними використовується шаблонізатор Apache Velocity. Саме він дозволяє реалізувати умовні оператори, цикли та інші операції з даними безпосередньо в тілі листа. Весь динамічний контент, доступний при відправленні, знаходиться в спеціальній системній змінній $data. Після завантаження файлу його треба вибрати під час формування листа.

Вибір файлу препроцесора

  1. Створіть повідомлення в редакторі.
  2. Відкрийте меню з трьома крапками, а потім натистніть Вибрати препроцесор.
  1. Виберіть тип препроцесора (у нашому прикладі це тип Key).
  1. Виберіть завантажений на попередньому етапі файл й натисніть застовувати.

Після цього файл буде використано під час відправлення повідомлення.

Використання даних у Velocity

Доступ до масиву даних

Визначений препроцесором масив даних розміщується в масиві з назвою recommendations. Щоб отримати до нього доступ, використовуйте таку конструкцію:

$data.get('recommendations')

Цикл по масиву

Щоб організувати цикл за цим масивом, використовуйте таку конструкцію:

#foreach($item in $data.get('recommendations'))
$item.get(‘name’)
…
#end

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

Умовний оператор

#if($item.get('discount') == 0)
    …
#else
    …
#end

У місці трикрапок можна використовувати будь-який HTML-код за умови збереження коректної структури повідомлення.

Якщо виникають складнощі з формуванням Velocity-коду або використанням препроцесора, звертайтеся до служби підтримки [email protected]

Тестування даних для розсилок

Для тестування використовуйте тестову групу контактів.

  • Для Key-препроцесора тестові контакти повинні бути присутні у файлі з даними.
  • Для Random-препроцесора можна використовувати будь-які контакти.

Приклади використання

Звертання до елементів за індексом

Такий вигляд має лист у режимі редагування:

Так може виглядати результат після підстановки динамічного контенту:

Звернення до елементів у циклі

Такий вигляд має лист у режимі редагування:

Так може виглядати результат після підстановки динамічного контенту:

Updated 23 days ago