Использование препроцессора

• Определение
• Поддерживаемые типы
• Как это работает
• Как загрузить файл для препроцессора
• Как создать письмо с использованием препроцессора
• Как протестировать данные для рассылок
• Примеры использования

Определение

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

С препроцессором всё это можно реализовать без интеграции с третьим сервисом, рутинным и бесполезным обновлением дополнительных полей контакта и использовать как в массовых рассылках, так и в триггерных письмах.

Кстати, пользоваться персонализацией можно не только в письмах, но и в 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 препроцессор и в каждом письме показывать любые случайные 3 модели. Тогда рюкзаки будут продаваться равномерно и успешность каждой позиции можно будет проверить по количеству продаж / переходов которые они принесли.

Пример файла:

{
    "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 дополнительно беспокоиться о наличии адресов в файле нет необходимости - можно тестировать на любые адреса.

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

Обращение к элементам по индексу

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

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

Обращение к элементам в цикле

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

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