Ниже описаны рекомендации по разработке модуля (плагина) для CMS и CRM систем, который обеспечит интеграцию между вашей CMS или CRM системой и Unisender.
Возможности интеграции
Если вы будете придерживаться рекомендаций, описанных ниже, то в результате получите модуль в вашей системе, который позволит пользователям:
- регистрироваться в Unisender или привязывать уже существующею учетную запись Unisender к модулю;
- импортировать email и другие поля контактов из вашей системы в Unisender для дальнейших рассылок по ним;
- создавать письма для рассылок;
- отправлять рассылку по импортированным email;
- получать статистику по рассылкам писем: количество доставленных, прочитанных писем и количество переходов по ссылкам.
Если при разработке у вас возникли вопросы по этому документу или вы хотите разработать интеграцию, которая отличается от описанной выше, вы можете обратиться на наш почтовый ящик plugins@unisender.com за консультацией.
Рекомендации к разработке в разрезе функций
При разработке интеграций вы будете использовать API Unisender
ВАЖНО
Для отслеживания пользователей вашей интеграции и диагностики ошибок, которые будут возникать, необходимо в каждый(!) вызов метода API добавлять параметр platform. Значения параметра — название вашей системы на латинице без пробелов и спецсимволов, предварительно согласованное с менеджером.
Для согласования параметра отправьте запрос на адрес plugins@unisender.com c кратким описанием вашей системы.
Пример вызова с этим параметром:
Метод создания списка имеет формат
GET
https://api.unisender.com/ru/api/createList?format=json&api_key=***&title=***
Вы должны при вызове этого метода добавлять параметр с названием вашей системы:
https://api.unisender.com/ru/api/createList?format=json&api_key=***&title=***&platform=MySite
Вход существующего пользователя Unisender
- Отобразить форму с полем API-ключ и информацию, как его получить и включить в Unisender.
- При подтверждении формы вызвать метод getLists.
- Если метод возвращает информацию о списках без ошибок, отобразить сообщение
«Вы успешно вошли в систему». - Перейти к пункту «Выбор списка и доп. полей для импорта контактов».
Регистрация пользователя
- Отобразить форму с полями Email и Пароль.
- При подтверждении заполнения формы отправить данные из полей формы методом register.
- Если метод отработал, вы получите API-ключ пользователя.
- Сохранить полученный API-ключ в вашем приложении.
- Отобразить пользователю сообщение о том, что регистрация прошла успешно.
- Перейти к пункту «Выбор списка и доп. полей для импорта контактов».
Выбор списка и доп. полей для импорта контактов
- Отобразить окно «Выберите список для импорта контактов или создайте новый», в котором отображаются названия списков, полученные методом getLists, а также окно для ввода названия нового списка.
- Если пользователь выбрал список, вы должны сохранить его id в вашей системе (далее id списка понадобится для импорта и создания письма).
- Если пользователь ввел название нового списка, вы должны его создать в Unisender методом createList и сохранить id полученного списка в системе.
- Отобразить сообщение «Список выбран».
- После подтверждения прочтения сообщения отобразить окно с маппингом (соответствие полей вашей системы и Unisender) полей контактов вашей системы и Unisender. Окно должно отображать доступные поля для импорта из вашей системы и поля Unisender. Поля Unisender можно получить методом getFields. Если пользователь хочет создать новое поле в Unisender нужно воспользоваться методом createField.
- При маппинге полей нужно согласовать типы полей.
- После маппинга полей пользователем нужно отобразить сообщение об успешном завершении маппинга.
- Перейти к пункту «Создание письма для рассылки».
Импорт контактов рекомендуем проводить непосредственно перед созданием рассылки.
Создание письма для рассылки
- Получить список подтвержденных адресов пользователя getCheckedEmail.
- Если пользователь хочет отправить рассылку от неподтвержденного ранее адреса, подтвердить адрес отправителя методом validateSender.
- После вызова метода validateSender отобразить сообщение «Вам на адрес отправлено письмо-подтверждение, после перехода по ссылке вы сможете отправлять рассылки с этого адреса».
- Создать письмо для отправки методом createEmailMessage. При создании письма указать список, выбранный на шаге «Выбор списка и доп. полей для импорта контактов». С помощью параметра attachments можно добавить вложения, максимальный размер — 500 Кб.
- Сохранить полученный id письма
- Предложить проверить отображение письма в почтовом ящике пользователя. Если пользователь согласен, отправить тестовое письмо методом sendTestEmail.
Отправка рассылки и получение статистики
- Пользователь может выбрать один из способов отправки:
- сразу;
- запланировать отправку.
2. Если пользователь подтвердил отправку (нажал на кнопку «Отправить рассылку» или «Запланировать отправку»), ваша система должна импортировать контакты в выбранный список на шаге «Выбор списка и доп. полей для импорта контактов», используя метод importContacts. При вызове метода importContacts в параметре fields указываются поля Unisender, куда нужно импортировать данные, а в параметре data — данные из полей вашей системы. Импортировать можно не более 500 контактов за вызов. После импорта нужно отобразить сообщение об успешном завершении импорта.
3. Вызвать метод createCampaign, в котором передать:- message_id — идентификатор письма, созданного на шаге «Создание письма для рассылки»;
- start_time — время отправки в зависимости от выбранного способа отправки;
- contacts_url — необязательный параметр, используется, если надо отправить рассылку не по всему списку, а только конкретному сегменту, содержит ссылку на файл с контактами, по которым должна отправиться рассылка;
- track_read = 1;
- track_links = 1.
4. В случае, если пользователь выберет способ отправки «отправить сразу», показать сообщение «Рассылка отправлена», если выберет «запланировать отправку», то «Отправка рассылки запланирована».
Получение статуса и статистики рассылки
Получить текущий статус рассылки можно методом getCampaignStatus.
Получить статистику по рассылке можно методом getCampaignCommonStats.
