Перші кроки
Дані користувача
- Огляд адаптивного email-редактора
- Cтворення оформлення для листа
- Створення синхронізованих модулів
- Налаштування адаптивності
- Налаштування Smart-елементів
- Оформлення промовкладки для Gmail
- Додавання Rolloverʼа
- Додавання фону до листа
- Додавання анкорних посилань
- Бібліотека блоків (Модулі)
- Додавання таблиці до листа
- Додавання кастомних шрифтів
- Додавання кастомних іконок соцмереж
- Створення кнопки СТA
- Робота з блоком "Зображення"
Омніканальність
- SDK для мобільних застосунків
- Керування ключами доступу до мобільного SDK
- Підключення мобільного застосунку
- Створення Google проекту для Mob Push
- Створення мобільних push-повідомлень
- Налаштування аналітики доставлень та кліків
- Планування мобільних push-повідомлень
- Налаштування універсальних посилань (deeplinks & Universal links)
- Надсилання тестових повідомлень із налагодження запитів
- Налаштування віджетів для сайту
- Виклик віджета
- Збереження даних із віджетів у поля контактів
- Захист від роздратування
- Дії після заповнення форми
- Розширення для тестування форм в Google Chrome
- Створення pop-up-форм за допомогою Google Tag Manager або WordPress
- Надсилання подій з віджетів eSputnik до Google Analytics
- Заміна системного сценарію Double Opt-In
- Налаштування геоданих для правил виклику віджетів
Автоматизація
- Подвійне підтвердження підписки
- Вітальна серія
- Вітальна серія із сегментацією за категоріями
- Запуск сценарію після імпорту контактів
- Регулярний сценарій для групи
- Вітання з днем народження
- Привʼязка сценарію до кнопки
- Реактивація клієнтів та підписників
- Відправка розсилки непрочитавшим
- Налаштування додаткових розсилок
Персоналізація
- Підстановка промокоду з файлу
- Підстановка промокоду з використанням API
- Принципи генерації промокодів за допомогою PHP/JAVA
- Підстановка промокоду за допомогою персоналізації
- Завантаження промокодів для використання в сценарії
- Генерація промокодів у сценарії
- Відправлення промокоду за допомогою передпроцесора
- HTTP-запит для передачі промокоду з повідомлення до картки контакту
Аналітика
- Звіт щодо email-розсилки
- Звіт щодо SMS-розсилки
- Звіт щодо розсилки Web Push
- Звіт щодо Viber-розсилки
- Звіт щодо розсилки Mob Push
- Звіт щодо розсилки App Inbox
- Звіт зі взаємодії з віджетами
- Звіт щодо тригерної розсилки
- Звіт щодо AMP-розсилки
- Звіт щодо мультимовної розсилки
- Налаштування передачі UTM-міток
- Візуалізація доходу
- Відстеження ефективності розсилок у Google Analytics
Мультимовність
Відстеження подій та поведінки
- Розгалуження сценарію в залежності від параметрів події
- Відстеження активності на сайті за допомогою 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 та приклади коду для їхнього виклику подані на ресурсі "API Reference".
Тут ми спробуємо відповісти на найбільш поширені питання про те, як користуватися API або вирішити конкретну проблему, з більш розгорнутими описами та прикладами, ніж в описі методів.
Як перевірити, що API працює, а параметри доступу правильні
Найпростіший варіант — це отримати інформацію про ваш акаунт: Get account info.
Розглянемо на прикладі додатка Postman, призначеного для простого тестування API. Завантажте додаток і встановіть його на комп'ютер. Щоб історія запитів збереглася, треба авторизуватися, але для швидкого тесту можна обійтися і без реєстрації в сервісі.
Перш за все оберіть Basic Auth у параметрах, вкладка Authorization, рядок Type:
Щоб авторизуватися, потрібно:
- ввести будь-яке значення в полі Username,
- ввести значення вашого API-ключа в полі Password.
Після чого:
- Виберіть метод. У нашому випадку це GET.
- Введіть ресурс. У нашому випадку це Get account info.
- Натисніть кнопку Send для відправлення запиту.
Так виглядатиме запит для отримання інформації про ваш акаунт:
Як відписати контакт, якщо відписку здійснено в особистому кабінеті користувача на сайті?
Для управління відпискою використовуйте ресурс API Add emails to unsubscribed list або Remove emails from unsubscribed list.
Важливо!
Ви відписуєте не конкретний контакт, а лише email користувача, тоді як інші медіаканали (SMS, Viber, push) залишаються доступними. Якщо в організації електронну адресу використовують кілька контактів, то всі вони перестануть отримувати масові розсилки після відписки.
1. Для додавання емейла до списку відписаних існує такий метод: Add emails to unsubscribed list.
Тіло запиту має такий вигляд:
{
"emails" : [ "test1@mail.com", "test2@mail.com" ]
}
emails – це список адрес, що будуть позначені як відписані.
2. Для видалення емейла зі списку відписаних використовується Remove emails from unsubscribed list.
Тіло запиту є таким самим, як у розглянутому вище ресурсі: ви вводите перелік адрес, які будуть видалені з відписаних.
Розглянемо ресурс Remove emails from unsubscribed list на прикладі в Postman:
- Задайте конфігурації:
- Виберіть метод запиту POST
- Введіть ресурс Remove emails from unsubscribed list
- У розділі Body виберіть raw та формат передачі даних JSON (application/json):
- Вкажіть тіло запиту в форматі:
{
"emails" : [ "...", ... ]
} - Натисніть Send для відправлення запиту:
Як використовувати динамічний контент у листах?
Реалізувати відправлення листа з динамічним контентом можна у два способи. Перший спосіб передбачає просту підстановку даних у тіло листа із запиту, що передається за допомогою 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, де {id} — ідентифікатор листа, до якого будуть підставлятися дані при відправленні одержувачу.
Тіло запиту в мінімальному вигляді:
{
"recipients" : [ {
"locator" : "...",
"jsonParam" : "..."
} ]
}
recipients – масив адрес одержувачів повідомлення.
locator – одержувач. Наприклад, email-адреса для email-повідомлень, номер телефону для SMS або Viber.
jsonParam — дані у вигляді json для підстановки в лист.
Метод дозволяє згенерувати різноманітний контент для кожного конкретного отримувача. Із цією метою передачу даних організовано парами "емейл + набір параметрів". Параметри передаються у вигляді довільної 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 ресурсу smartsend".
Як використовувати event-и для тригерів, наприклад "Ваше замовлення оформлене"
За допомогою API дуже зручно відправляти тригери, використовуючи метод API Generate event. Усі зовнішні дані, що надходять у повідомлення, потрапляють до об'єкта data. Щоб вивести потрібний параметр, прописуємо $!data.get('ім'я параметра'). Для цього вам необхідно:
Підготувати тіло запиту.
Мінімальне тіло запиту має вигляд:
{
"eventTypeKey": "...",
"keyValue": "...",
"params": [{
"name": "...",
"value": "..."
}, ... ]
}
де
eventTypeKey – идентификатор-ключ типа события. Если в системе нет типа события с таким ключом, то он создастся автоматически;
eventTypeKey — ідентифікатор-ключ типу події. Якщо в системі немає типу події з таким ключем, то він створюється автоматично;
keyValue — ідентифікатор події, може збігатися з ідентифікатором або email-ом контакту;
name — ім'я параметра;
params — список параметрів.
- Створити лист з динамічним контентом, який ви бажаєте відправляти (Повідомлення → Повідомлення → Створити Email).
Зверніть увагу! Значення в лапках після $!data.get має відповідати значенню name в масиві параметрів params, який ви передаватимете в запиті. - Створити сценарій, щоб контент, який передається ресурсом Generate event, підставлявся в тіло повідомлення (Тригери → Сценарії → Додати сценарій).
- Створити подію (Тригери → Типи подій → Додати тип події) з ключем, що буде використаний у запиті (поле eventTypeKey), і прив'язати до події сценарій, створений на попередньому етапі.
Заздалегідь створювати подію в акаунті не обов'язково.
Після того, як ви передасте перший запит, подію в акаунті буде створено автоматично.
Для тестування треба викликати запит у Postman.
- Задайте конфігурації:
- Виберіть метод запиту POST
- Введіть ресурс Generate event
- У розділі Body виберіть raw і формат передачі даних JSON (application/json).
- Укажіть тіло запиту в форматі:
Після натискання кнопки Send запит буде відправлений, і протягом хвилини ми отримаємо лист такого вигляду:
Після успішного відправлення запиту ви можете перевірити правильність виконання:
1) передачі події в систему: Тригери → Історія подій;
2) відправлення листа: Розсилки → Одиночні;
3) отримання листа із правильно підставленими елементами: Лист у вхідних.
Як передавати замовлення за 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. За цим параметром у системі визначається унікальність замовлень.
Перевірити, чи потрапило замовлення до системи й чи коректно передані поля, можна в особистому кабінеті в розділі Тригери → Замовлення. Клікнувши ID замовлення, ви побачите всі поля в форматі JSON.
Як отримати статус відправленого повідомлення через API?
Якщо ви відправляєте одиночні повідомлення ресурсами Send prepared message, Send email message, Send SMS message, Send viber message, то відправлення відбувається в асинхронному режимі. А саме: після запиту до API ваше повідомлення ставиться в чергу на відправлення і через деякий час (зазвичай протягом кількох секунд) відправляється. У відповідь на кожен із цих запитів ви отримаєте таку структуру:
{
"id": "0",
"results": {
"id": "0",
"locator": "test@mail.com",
"status": "OK",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
}
}
Після чого для отримання статусу цього повідомлення, а також будь-якого повідомлення, відправленого через будь-який канал, треба викликати GET-запит Get single message status.
Параметр ids — це список ідентифікаторів requestId, розділених комою. Ви отримаєте таку відповідь:
{
"results": {
"status": "DELIVERED",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
"failed": "false",
"delivered": "true"
}
}
Як інтегрувати форму підписки через API?
Для інтеграції форми підписки необхідно викликати ресурс Subscribe 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 — це список додаткових полів, що передаються попарно: ідентифікатор поля + значення
Отримати ідентифікатори всіх додаткових полів, які існують у вашій організації, можна двома способами.
Перший — переглянути ідентифікатори в Меню акаунта → Налаштування → Додаткові поля.
Другий — викликати ресурс Get catalog list. Це GET-метод без параметрів, що поверне вам структуру, подібну до цієї:
{
"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 на реальних розсилках