Инструкция по созданию интеграций

Рекомендации по разработке интеграции UniSender и CMS/CRM

Возможности интеграции

Ниже описаны рекомендации по разработке модуля (плагина) для 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

1. Отобразить форму с полем API ключ и информацию как его получить и включить в UniSender.
2. При подтверждении формы вызвать метод getLists.
3. Если метод возвращает информацию о списках без ошибок, отобразить сообщение
   «Вы успешно вошли в систему».
4. Перейти к пункту «Выбор списка и доп. полей для импорта контактов».

Регистрация пользователя

1. Отобразить форму с полями Email & Password.
2. При подтверждении заполнения формы отправить данные из полей формы методом register.
3. Если метод отработал - вы получите API ключ пользователя.
4. Сохранить полученный API ключ в вашем приложении.
5. Отобразить пользователю сообщение - что регистрация прошла успешно.
6. Перейти к пункту «Выбор списка и доп полей для импорта контактов».

Выбор списка и доп полей для импорта контактов

1. Отобразить окно «Выберите список для импорта контактов или создайте новый», в котором отображаются названия списков, полученных методом getLists и окно для ввода названия нового списка.
2. Если пользователь выбрал список, вы его id должны сохранить в вашей системе.
3. Если пользователь ввел название нового списка, вы должны его создать в UniSender методом createList и сохранить id полученного списка в своей системе.
4. Отобразить сообщение «Список выбран».
5. После подтверждения прочтения сообщения отобразить окно с маппингом (соответствие полей вашей системы и UniSender) полей контактов вашей системы и UniSender. Окно должно отображать доступные поля для импорта из вашей системы и поля UniSender. Поля UniSender можно получить методом getFields. Если пользователь хочет создать новое поле в UniSender нужно воспользоваться методом createField.
6. При маппинге полей нужно согласовать типы полей.
7. После маппинга полей пользователем, нужно отобразить сообщение об успешном завершении маппинга.
8. Перейти к пункту «Создание письма для рассылки».

Импорт контактов рекомендуем проводить непосредственно перед созданием рассылки.

Создание письма для рассылки

1. Получить список подтвержденных адресов пользователя getCheckedEmail.
2. Если пользователь хочет отправить рассылку от неподтвержденного ранее адреса, подтвердить адрес отправителя методом validateSender.
3. После вызова метода validateSender отобразить сообщение «Вам на адрес отправлено письмо подтверждения, после перехода по ссылке вы сможете отправлять рассылки с этого адреса».
4. Создать письмо для отправки методом createEmailMessage. При создании письма указать список выбранный на шаге «Выбор списка и доп полей для импорта контактов»:- attachments -добавить вложения. максимальный размер вложения 500 Кб
   - message_format = raw_html
5. Сохранить полученный id письма
6. Предложить проверить отображение письма в почтовом ящике пользователя. Если пользователь согласен - отправить тестовое письмо методом sendTestEmail.

Отправка рассылки по созданному письму и получение статистики

1. Пользователь может выбрать один из способов отправки:- сразу;
   - запланировать отправку.
2. Если подтвердил отправку ваша система должна импортировать контакты в выбранный список на шаге «Выбор списка и доп полей для импорта контактов», используя метод importContacts
3. Вызвать метод createCampaign в котором передать:- message_id - идентификатор письма, созданного на шаге «Создание письма для рассылки»;
   - start_time - установить время отправки в зависимости от выбранного способа отправки;
   - contacts_url - ссылку на файл с контактами, которым должна отправиться рассылка и были добавлены методом importContacts (сегмент - часть импортированных контактов);
   - track_read = 1;
   - track_links = 1.
4. Показать сообщение «Отправка рассылки запланирована успешно».

Получение статуса и статистики рассылки

1. Получить текущий статус рассылки можно методом getCampaignStatus.
2. Получить статистику по рассылке можно методом getCampaignCommonStats.