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

• Визначення
• Підтримувані типи
• Як це працює
• Як завантажити файл для препроцесора
• Як створити лист із використанням препроцесора
• Як протестувати дані для розсилок
• Приклади використання

Визначення

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

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

До речі, користуватися персоналізацією можна не тільки в листах, але також у SMS-повідомленнях. 

Можливості препроцесора є дуже широкими і не обмежуються існуючим функціоналом. Ми можемо легко розширювати їх, додаючи нову логіку обробки зовнішніх масивів даних. Тож якщо комусь потрібно "дивне" — пишіть, ми обговоримо ваші потреби й постараємося в найкоротші терміни реалізувати їх.

Підтримувані типи

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

• Key 
• Random

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

Вибирає з масиву даних структуру за заданим ключем, наприклад  за email, і передає її до шаблону листа перед відправленням. Ви можете підготувати список персональних рекомендацій спеціально для кожного контакту в форматі {email: json з рекомендаціями}, де email постає в ролі ключа. І під час відправлення розсилки для всіх контактів з email зі списку препроцесора буде отриманий свій json, який буде використано в листі.

З таким підходом кожному підписникові можна показувати свій набір рекомендованих товарів, акцій та спеціальних пропозицій.

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

{
    "example@yoursite.com": [
    {
        "name": "book",
        "price": "11"
    },
    {
        "name": "ball",
        "price": "22"
    }, 
    {
        "name": "game",
        "price": "33"
    }],
    "example-2@yoursite.com": [
    {
        "name": "food",
        "price": "44"
    },
    {
        "name": "drink",
        "price": "55"
    }]
}

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

Із підготовленого масиву даних вибирає випадкові кілька json-структур і передає їх у лист. Ви напевно чули, що блок у листі з товарними пропозиціями працює дуже добре. Уявіть, що у вас велика контактна база й величезний асортимент товарів. Ви бажаєте, наприклад, запропонувати рюкзаки для школи за дуже привабливою ціною. Якщо вказати якийсь конкретний рюкзак, його швидко розкуплять, тож іншим доведеться відмовляти й пропонувати альтернативу.

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

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

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

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

а) вказати змінну у велосіті-коді: $forEachLimit=2;

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

Як це працює

У цьому розділі основний акцент зроблено на технічній складовій реалізації. Якщо ви не програміст і нічого тут не зрозуміли, це не обов'язково — тож не впадайте у відчай. Але щоб отримати уявлення про те, що під капотом, рекомендую ознайомитися з цим розділом.

Щоб механізм препроцесора запрацював, треба налаштувати дві його взаємопов'язані частини. По-перше, створити файл із структурою даних у необхідному для завантаження форматі; по-друге, додати до листа код, за допомогою якого динамічний контент буде згенеровано й підставлено в лист "на льоту" при відправленні.

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

{“test1@mail.com” : [{...}, {...}], “test2@mail.com” : [{...}, {...}, {...}], “test3@mail.com” : [{...}, {...}]}, 

де test1@mail.com, test2@mail.com, test3@mail.com — емейл-адреса (або номер телефону) одержувача, кожному з яких відповідає масив даних для підстановки в лист.

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

{“test@mail.com” : [{...}, {...}, {...}, {...}, {...}, {...}]},

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

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

Як завантажити файл для препроцесора

Є два варіанти передачі файлів із даними до системи.

Варіант 1. За допомогою API

Механізм передачі файлу за API, який дозволяє завантажити файл із даними до системи, має такий вигляд:

1. Завантажити файл, який містить динамічний контент у форматі json, для підстановки в лист за допомогою велосіті (API методом POST Upload file for preprocessor). У відповіді на цей запит повертається ідентифікатор файлу, який надалі можна використовувати для його оновлення.

2. Оновити вже завантажений файл (API метод POST Update file for preprocessor).

3. Отримати статус завантаженого/завантажуваного файлу (API метод GET Get preprocessor file status).

4. Вибрати файл у листі й використовувати підстановку контенту під час розсилок або в тригерних одиночних (IMCallout — сценарій або метод Send prepared message).

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

Варіант 2. В особистому кабінеті

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

• У вашому акаунті eSputnik увійдіть до налаштувань;

  

• Виберіть вкладку "Препроцесор" і натисніть кнопку "Завантажити"

• Виберіть тип препроцесора. Для прикладу виберемо тип Key (налаштування препроцесора з типом Random відбуватиметься аналогічно).

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

• Потім натискаємо "Почати завантаження"

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

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

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

• після створення листа в редакторі повідомлень натисніть три крапки і клікніть "Вибрати обробник";

• у нас уже вибрано тип препроцесора (у цьому прикладі вибраний тип Random; для додавання файлу препроцесора типу Key здійснюються аналогічні дії);

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

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

Визначений препроцесором масив даних розміщується в масиві з назвою "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-коду в листі або ви маєте запитання щодо складніших прикладів його використання, аніж описані в цьому розділі, — звертайтеся до нашої служби підтримки support@esputnik.com. Ми із задоволенням надамо допомогу й поділимося знаннями.

Як протестувати дані для розсилок

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

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

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

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

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

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

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

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