Перші кроки
Дані користувача
- Огляд адаптивного email-редактора
- Cтворення оформлення для листа
- Створення синхронізованих модулів
- Налаштування адаптивності
- Налаштування smart-контейнерів
- Оформлення промовкладки для Gmail
- Додавання Ролловера
- Додавання анкорних посилань
- Бібліотека модулів
- Додавання таблиці до листа
- Додавання кастомних шрифтів
- Створення кнопки СТA
- Робота з блоком "Зображення"
- Робота з блоком “Таймер"
- Використання ШІ в email-редакторі
Омніканальність
- SDK для мобільних застосунків
- Керування ключами доступу до мобільного SDK
- Підключення мобільного застосунку
- Створення та завантаження ключа Firebase
- Створення мобільних push-повідомлень
- Налаштування аналітики доставлень та кліків
- Планування мобільних push-повідомлень
- Типи діплінків
- Надсилання тестових повідомлень із налагодження запитів
- Налаштування віджетів для сайту
- Виклик віджета
- Налаштування геоданих для правил виклику віджетів
- Збереження даних із віджетів у поля контактів
- Захист від роздратування
- Дії після заповнення форми
- Заміна системного сценарію Double Opt-In
- Створення pop-up-форм за допомогою Google Tag Manager або WordPress
- Надсилання подій з віджетів eSputnik до Google Analytics
- A/B-тестування віджетів
- Збір контактних даних за допомогою форм запитів
Автоматизація
- Налаштування та редагування сценаріїв
- Налаштування умов запуску та зупинки сценарію
- Блок “Старт”
- Група блоків “Популярні”
- Група блоків “Повідомлення”
- Використання блока повідомлень “Одне з багатьох”
- Група блоків “Контакт”
- Група блоків "Умови"
- Група блоків “Інше”
- Група блоків “Повідомлення на групу”
- Група блоків “Час”
- Розширені параметри блоків сценаріїв
- Дозволений час відправлення
- Вебхуки в сценаріях
- Відстеження історії запусків сценарію
- Якщо сценарій не працює
- Подвійне підтвердження підписки
- Вітальна серія
- Вітальна серія із сегментацією за категоріями
- Запуск сценарію після імпорту контактів
- Регулярний сценарій для групи
- Вітання з днем народження
- Привʼязка сценарію до кнопки
- Використання змінних із замовлення у сценарії
- Збір відгуків про замовлення
- Реактивація клієнтів та підписників
- Відправка розсилки непрочитавшим
- Налаштування додаткових розсилок
- Відправлення нагадувань в заданий користувачем час
- А/B-тестування в сценаріях
Персоналізація
- Підстановка промокоду з файлу
- Підстановка промокоду з використанням API
- Принципи генерації промокодів за допомогою PHP/JAVA
- Підстановка промокоду за допомогою персоналізації
- Завантаження промокодів для використання в сценарії
- Генерація промокодів у сценарії
- Відправлення промокоду за допомогою передпроцесора
- HTTP-запит для передачі промокоду з повідомлення до картки контакту
Аналітика
- Звіт щодо email-розсилки
- Звіт щодо SMS-розсилки
- Звіт щодо розсилки Web Push
- Звіт щодо Viber-розсилки
- Звіт щодо розсилки Mob Push
- Звіт щодо розсилки App Inbox
- Звіт щодо Telegram-розсилки
- Звіт зі взаємодії з In-App
- Звіт зі взаємодії з віджетами
- Звіт щодо тригерної розсилки
- Звіт щодо AMP-розсилки
- Звіт щодо мультимовної розсилки
- Налаштування передачі UTM-міток
- Візуалізація доходу
- Відстеження ефективності кампаній у Google Analytics 4
- Статистика повідомлень
Мультимовність
Відстеження подій та поведінки
- Події для запуску тригерних розсилок
- Найменування користувацьких подій
- Валідація параметрів подій
- Відстеження активності на сайті за допомогою Generate event
- Підстановка даних з подій в повідомлення
- Розгалуження сценарію в залежності від параметрів події
- Відстеження активності клієнтів у мобільних застосунках
- Вебхуки для відстеження активності
- Аналітика подій
Товарні рекомендації
API
- Поширені питання: Інтеграція з API
- API-ключі
- Ресурси API для додавання контактів
- Використання API-ресурсу Generate event
- Передача замовлень API-ресурсом Generate event
- Отримання рекомендацій щодо API ресурсом Contact recommendations based on web tracking
- Використання API-ресурсу Send prepared message
Зміна системи
Документи
Інтеграція
Поширені питання: Інтеграція з API
У цій статті ви знайдете відповіді на найпоширеніші питання про інтеграцію з API eSputnik.
Вся технічна документація щодо формату даних для виклику API-запитів знаходиться за посиланням.
Як перевірити, що API працює, а параметри доступу правильні?
Наприклад, ви можете отримати інформацію про ваш акаунт за допомогою методу Get account info. Для цього виконайте наступні кроки.
1. Згенеруйте ключ API та скопіюйте його до буфера обміну.
2. Перейдіть на сторінку https://docs.esputnik.com/reference/getaccountinfo-1.
3. Введіть ім’я користувача та пароль, який є скопійованим ключем API, над прикладом запиту.
4. Натисніть Try it!
У відповіді ви маєте побачити ім’я користувача та назву своєї організації:
Як відписати контакт, якщо відписку здійснено в особистому кабінеті користувача на сайті?
Для управління відпискою використовуйте метод API Add emails to unsubscribed list та Remove emails from unsubscribed list.
Важливо
Відписується лише email користувача, тоді як інші медіаканали (SMS, Viber, Push тощо), якщо вони є в його контактній картці, залишаються доступними. Якщо електронну адресу використовують кілька контактів, то всі вони перестануть отримувати масові розсилки після відписки.
Тіло запиту Add emails to unsubscribed list має такий вигляд:
{
"emails" : [ "test1@mail.com", "test2@mail.com" ]
}
де emails – це список адрес, що будуть позначені як відписані.
Тіло запиту Remove emails from unsubscribed list є таким самим: воно має містити перелік адрес, які будуть видалені з відписаних.
Розглянемо роботу з методом Remove emails from unsubscribed list:
1. Перейдіть на сторінку https://docs.esputnik.com/reference/deletefromunsubscribed-1.
2. В BODY PARAMS натисніть ADD STRING і введіть до рядків адреси відписаних контактів.
3. Натисніть Try it!
Якщо адреси з запиту були у відписаних у вашому акаунті eSputnik, вони видаляться з цього списку.
Як використовувати динамічний контент у повідомленнях?
Реалізувати відправлення листа з динамічним контентом можна у два способи:
- За допомогою сценарію
- За допомогою методу Send prepared message
За допомогою сценарію
Цей спосіб передбачає просте підставляння даних у повідомлення із запиту, що передається за допомогою API-методу Generate event. Масив params може містити довільну кількість об'єктів такого вигляду
{
"name": "назва поля",
"value": "значення поля"
}
Для підставлення даних у повідомлення скористайтеся змінними Velocity.
Наприклад, передано такий запит:
{
"eventTypeKey": "testEvent",
"keyValue": "example@email.com",
"params": [{
"name": "discount",
"value": "5%"
},{
"name": "link",
"value": "https://example.site.com/items_for_sale"
}
]
}
У повідомленні необхідно використовувати змінні $!data.get('discount') та $!data.get('link'), замість яких будуть підставлятися дані з запиту.
Щоб контент, який передається методом Generate event, підставлявся в тіло повідомлення, підготуйте сценарій з використанням цього повыдомлення, що запускатиметься відповідною подією. Докладніше >
За допомогою методу Send prepared message
Цей спосіб передбачає відправлення повідомлень без використання сценарію методом Send prepared message, де {id} в посиланні https://esputnik.com/api/v1/message/{id}/smartsend — ідентифікатор повідомлення, до якого будуть підставлятися дані при відправленні одержувачу.
Тіло запиту в мінімальному вигляді:
{
"recipients" : [ {
"locator" : "...",
"jsonParam" : "..."
} ]
}
де:
- recipients – масив з контактними даними одержувачів повідомлення;
- locator – одержувач, наприклад — email-адреса для email-повідомлень, номер телефону для SMS або Viber;
- jsonParam — дані у вигляді JSON для підставлення до повідомлення.
Метод дозволяє згенерувати різноманітний контент для кожного конкретного отримувача за допомогою змінних Velocity. З цією метою передавання даних організовано парами "емейл + набір параметрів". Параметри передаються у вигляді довільної JSON-структури, до всіх полів якої в тілі повідомлення можна звернутися так: $data.get('field_name').
Також в коді листа можна:
- Задати умову відображення будь-якого блоку html-коду: #if($data.get('field_name').equals('0')) ... #end.
- Організувати цикл за елементами масиву: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... #end.
- Здійснювати в тілі листа арифметичні операції зі значеннями полів.
Зверніть увагу, що подвійні лапки всередині JSON-структури з параметрами мають екрануватися: "jsonParam" : "{\"field1\":\"value1\", ... }".
Подробиці можна дізнатися в статті "Використання API-ресурсу Send prepared message".
Як використовувати події для тригерів?
Тригерні розсилки можуть запускатися API-методом Generate event. Цей метод підходить для створення будь-яких кастомних подій, докладніше — за посиланням.
Також ми рекомендуємо викорситовувати метод Generate event для передавання замовлень. Інструкції >
Як передавати замовлення через API, наприклад, для його підтвердження?
Для передавання замовлень також можна використовувати метод Add orders. Запит може містити від 1 до 1000 замовлень. Щоб підставляти в листи товари, передавайте у замовленнях масив items із даними цих товарів. Якщо дані товарів у листах не потрібні, або ви використовуєте замовлення тільки для RFM-аналізу, масив можна не передавати.
Приклад тіла запиту:
{
"orders": [{
"externalOrderId": "100500",
"externalCustomerId": "12345",
"totalCost": 1000,
"status": "INITIALIZED",
"date": "2017-03-08T09:30:00+02:00",
"email": "mail@example.com",
"phone": "380942583691",
"firstName": "John",
"lastName": "Smith",
"currency": "USD",
"shipping": 10,
"discount": 0,
"deliveryMethod": "express",
"paymentMethod": "cash",
"deliveryAddress": "First str. 1",
"items": [{
"externalItemId": "200600",
"name": "Super Device",
"category": "devices",
"quantity": 1,
"cost": 990,
"url": "http://example.com/item/200600",
"imageUrl": "http://example.com/item/200600/image.png",
"description": "High quality"
}]
}]
}
Кожне замовлення має містити такі обов'язкові поля:
Відповідь на успіший запит матиме статус 200.
Для замовлень можна використовувати кілька статусів:
- Для щойно створеного замовлення – INITIALIZED.
- Для замовлення в процесі доставляння – IN_PROGRESS.
- Для сплаченого та доставленого замовлення – DELIVERED.
- Для скасованих замовлень – CANCELLED.
Важливо
Для формування RFM-аналізу використовуються тільки замовлення зі статусом DELIVERED.
Щоб оновити статус або інші дані замовлення, передавайте оновлене замовлення з тим самим externalOrderId. За цим параметром у системі визначається унікальність замовлень.
Перевірити, чи потрапило замовлення до системи та чи коректно передані поля, можна в особистому кабінеті в розділі “Тригери” → “Замовлення”. За кліком на замовлення ви побачите всі його поля в форматі JSON.
Більше про використання інформації про замовлення в листах >
Як отримати статус відправленого повідомлення через API?
Якщо ви відправляєте одиночні повідомлення методами
відправлення відбувається в асинхронному режимі: після запиту до API ваше повідомлення ставиться в чергу на відправлення і через деякий час (зазвичай протягом кількох секунд) відправляється. У відповідь ви отримаєте таку структуру:
{
"id": "0",
"results": {
"id": "0",
"locator": "test@mail.com",
"status": "OK",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
}
}
Для отримання статусу такого повідомлення треба викликати запит Get single message status.
Параметр ids – це список ідентифікаторів requestId, розділених комою. Ви отримаєте таку відповідь:
{
"results": {
"status": "DELIVERED",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
"failed": "false",
"delivered": "true"
}
}
Як інтегрувати форму підписки через API?
eSputnik пропонує вбудовану функціональність для створення віджетів без необхідності додаткових налаштувань API.
Для інтеграції форми підписки, створеної за допомогою стороннього сервісу, викличте запит методом Subscribe a contact. Мінімальне тіло запиту має такий вигляд:
{
"contact" : {
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
У системі з'явиться контакт з email-адресою.
Щоб задати ім'я контакту, додайте до тіла запиту поле firstName в об'єкті contact:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
Щоб указати, до яких груп потрапить контакт, що підписався, додайте до запиту поле groups — масив рядкових значень назв груп. Якщо якісь групи не існують у системі, вони будуть створені автоматично:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
},
"groups" : [ "Subscribers" ]
}
Після виклику в системі автоматично генерується одна з двох подій:
- subscribeFromAPI — у разі створення нового контакту;
- subscribeUpdateFromAPI — якщо такий контакт уже існує.
Ці події ви можете побачити в розділі “Тригери” → “Історія подій”.
До будь-якого типу події можна прив'язати сценарій, який буде запущено в момент генерації даної події. Рекомендуємо відправити новому контактові листа для підтвердження підписки.
Щоб переконатися, що новий контакт створено, перейдіть до розділу “Контакти” → “Всі контакти”, після чого введіть у поле пошуку потрібний ідентифікатор.
Ви побачите, що емейл контакту має сірий колір, — це означає, що він неактивний і потребує підтвердження від власника.
На такі адреси неможливо відправити розсилку, вони можуть отримувати тільки листи для підтвердження підписки та інші тригерні повідомлення, наприклад — лист про покинутий кошик або підтвердження оформленого замовлення.
Як передати значення додаткових полів контакту через API?
Розглянемо оновлення додаткових полів на прикладі методу Add/update contacts. Мінімальне тіло запиту з додатковими полями має такий вигляд:
{
"contacts": [{
"channels": [{
"type": "email",
"value": "test@mail.com"
}],
"fields": [{
"id": 15868,
"value": "ж"
}]
}],
"customFieldsIDs": [12345]
}
де
- channels — це список медіаканалів контакту; в даному прикладі передається один медіаканал — емейл;
- fields — це список додаткових полів, що передаються попарно: ідентифікатор поля + значення.
Отримати ідентифікатори всіх додаткових полів, які існують у вашій організації, можна двома способами.
1. Переглянути ідентифікатори в налаштуваннях акаунта на вкладці “Додаткові поля”.
2. Викликати запит методом Get the list of catalogs. Це метод без параметрів, що поверне вам структуру, подібну до цієї:
{
"addressBook": {
"addressBookId": "7200",
"name": "Основний",
"fieldGroups": {
"name": "Personal",
"fields": [
{
"id": "15867",
"name": "День народження",
"description": {
"type": "date",
"required": "false",
"readonly": "false"
}
},
{
"id": "15868",
"name": "Стать",
"description": {
"type": "combobox",
"allowedValues": {
"possibleValues": [
"ч",
"ж"
]
},
"required": "false",
"readonly": "false"
}
}
]
}
}
}
Список fields — це перелік усіх ваших додаткових полів. Окрім іншої інформації, кожен об'єкт цього списку містить ідентифікатор поля, який ви маєте використовувати під час передавання його значення.
Як тестувати API за допомогою Postman?
Postman – це популярний інструмент для тестування API. Він надає зручний інтерфейс для створення, відправлення та відстеження запитів.
Для початку роботи з Postman завантажте та встановіть його на комп'ютер.
Тестування методу Get account info
1. Оберіть Basic Auth у параметрах, вкладка Authorization, рядок Type:
2. Авторизуйтеся:
- введіть будь-яке значення в полі Username,
- введіть значення вашого API-ключа в полі Password.
3. Виберіть метод GET та введіть посилання https://esputnik.com/api/v1/account/info.
4. Натисніть кнопку Send.
У відповіді ви маєте побачити ім’я користувача та назву своєї організації:
{
"userEmail": "api-user162065",
"organisationName": "ExamleName"
}
Тестування методу Remove emails from unsubscribed list
1. Виберіть метод запиту POST та введіть посилання https://esputnik.com/api/v1/emails/unsubscribed/delete.
2. У розділі Body виберіть raw та формат передавання даних JSON.
3. Вкажіть тіло запиту в форматі:
{
"emails" : [ "...", "..." ]
}
4. Натисніть Send.
Якщо адреси з запиту були у відписаних у вашому акаунті eSputnik, вони видаляться з цього списку.
Тестування методу Generate event v2
1. Виберіть метод запиту POST та введіть посилання https://esputnik.com/api/v2/event.
2. У розділі Body виберіть raw і формат передавання даних JSON.
3. Вставте код події в тіло запиту в такому форматі:
{
"eventTypeKey": "create_contact",
"keyValue": "site@com.net",
"params":
[
{
"name": "email",
"value": "site@ukr.net"
},
{
"name": "phone",
"value": "380501234567"
},
{
"name": "externalCustomerId",
"value": "AV13760"
},
{
"name": "json",
"value":
{
"profileInputs":
[
{
"profileInputId": 10001,
"value": "2020-11-23"
}
]
}
}
]
}
4. Натисніть Send.
Успішно переданий запит відобразиться в історії подій в акаунті eSputnik.