Нижче подано рекомендації з розробки модуля (плагіну) для CMS і CRM-систем, який забезпечить інтеграцію між вашою CMS або CRM-системою та Selzy.
Можливості інтеграції
Якщо Ви будете дотримуватися цих рекомендацій, в результаті отримаєте модуль у Вашій системі, який дозволить користувачам:
- реєструватися в Selzy або прив'язувати вже наявний обліковий запис Selzy до модуля;
- імпортувати email та інші поля контактів із Вашої системи в Selzy для подальших розсилок на них;
- створювати листи для розсилок;
- відправляти розсилку імпортованим email-адресам;
- отримувати статистику щодо розсилок листів: кількість доставлених, прочитаних листів і кількість переходів за посиланнями.
Якщо під час розробки у Вас з’явилися питання щодо цього документу або Ви хочете розробити інтеграцію, яка відрізняється від описаної, Ви можете звернутися на нашу поштову скриньку [email protected] за консультацією.
Рекомендації до розробки в розрізі функцій
Під час розробки інтеграцій Ви будете використовувати API Selzy.
ВАЖЛИВО
Для відстеження користувачів Вашої інтеграції та діагностики майбутніх помилок необхідно в кожний (!) виклик методу API додавати параметр platform. Значення параметра — назва Вашої системи латиницею без пробілів і спецсимволів, попередньо узгоджена з менеджером.
Для узгодження параметра надішліть запит на адресу [email protected] із коротким описом Вашої системи.
Приклад виклику з цим параметром:
Метод створення списку має формат
GET
https://api.selzy.com/ua/api/createList?format=json&api_key=***&title=***
Ви повинні в разі виклику цього методу додавати параметр із назвою Вашої системи:
https://api.selzy.com/ua/api/createList?format=json&api_key=***&title=***&platform=MySite
Вхід наявного користувача Selzy
- Показати форму з полем API-ключ і інформацію, як його отримати та увімкнути в Selzy.
- Під час підтвердження форми викликати метод getLists.
- Якщо метод повертає інформацію про списки без помилок, відобразити повідомлення «Ви успішно увійшли в систему».
- Перейти до пункту «Вибір списку та дод. полів для імпорту контактів».
Реєстрація користувача
- Показати форму з полями Email і Пароль.
- Під час підтвердження заповнення форми надіслати дані з полів форми методом register.
- Якщо метод спрацював, Ви отримаєте API-ключ користувача.
- Зберегти отриманий API-ключ у Вашому додатку.
- Показати користувачеві повідомлення про те, що реєстрація відбулася.
- Перейти до пункту «Вибір списку та дод. полів для імпорту контактів».
Вибір списку та дод. полів для імпорту контактів
- Показати вікно «Виберіть список для імпорту контактів або створіть новий», в якому відображаються назви списків, отримані методом getLists, а також вікно для введення назви нового списку.
- Якщо користувач вибрав список, Ви повинні зберегти його id у Вашій системі (далі id списку знадобиться для імпорту контактів та створення листа).
- Якщо користувач ввів назву нового списку, Ви повинні його створити в Selzy методом createList і зберегти id отриманого списку в системі.
- Показати повідомлення «Список обрано».
- Після підтвердження прочитання повідомлення показати вікно з мапінґом (відповідність полів Вашої системи та Selzy) полів контактів Вашої системи та Selzy. Вікно має зображати доступні поля для імпорту з Вашої системи та поля Selzy. Поля Selzy можна отримати методом getFields. Якщо користувач хоче створити нове поле в Selzy, потрібно скористатися методом createField.
- Під час мапінґу полів потрібно узгодити типи полів.
- Після мапінґу полів користувачем потрібно відобразити повідомлення про успішне його завершення.
- Перейти до пункту «Створення листа для розсилки».
Імпорт контактів рекомендуємо робити безпосередньо перед створенням розсилки.
Створення листа для розсилки
- Отримати список підтверджених адрес користувача getCheckedEmail.
- Якщо користувач хоче надіслати розсилку від непідтвердженої раніше адреси, підтвердити адресу відправника методом validateSender.
- Після виклику методу validateSender відобразити повідомлення «Вам на адресу надіслано лист-підтвердження, після переходу за посиланням Ви зможете надсилати повідомлення з цієї адреси».
- Створити лист для надсилання методом createEmailMessage. Під час створення листа зазначити список, обраний на етапі «Вибір списку та дод. полів для імпорту контактів». За допомогою параметра attachments можна додати вкладення, максимальний розмір — 500 КБ.
- Зберегти отриманий id листа
- Запропонувати перевірити відображення листа в поштовій скриньці користувача. Якщо користувач згоден, надіслати тестовий лист методом sendTestEmail.
Відправка розсилки та отримання статистики
1. Користувач може обрати один зі способів віправки:
- одразу;
- запланувати відправку.
2. Якщо користувач підтвердив відправку (натиснув на кнопку «Відправити розсилку» або «Запланувати розсилку»), Ваша система повинна імпортувати контакти в обраний список на етапі «Вибір списку та дод. полів для імпорту контактів», використовуючи метод importContacts. У разі виклику методу importContacts у параметрі fields зазначаються поля Selzy, у які потрібно імпортувати дані, а в параметрі data — дані з полів Вашої системи. Імпортувати можна не більше 500 контактів за виклик. Після імпорту потрібно відобразити повідомлення про успішне завершення імпорту.
3. Викликати метод createCampaign, у якому передати:
- message_id — ідентифікатор листа, створеного на кроці «Створення листа для розсилки»;
- start_time — час надсилання залежно від обраного способу;
- contacts_url — необов'язковий параметр, використовується, якщо треба відправити розсилку не всьому списку, а тільки конкретному сегменту, містить посилання на файл із контактами, за якими треба відправити розсилку;
- track_read = 1;
- track_links = 1.
4. Якщо користувач обере спосіб відправки «Відправити відразу», показати повідомлення «Розсилку відправлено», якщо обере «Запланувати розсилку», то «Відправка розсилки запланована».
Отримання статусу та статистики розсилки
Отримати поточний статус розсилки можна методом getCampaignStatus.
Отримати статистику по розсилці можна за допомогою методу getCampaignCommonStats.