Використання API-ресурсу event
Будучи універсальним, ресурс v1/event може бути використаний для передавання до листа будь-яких кастомних даних. Наприклад, даних:
- про зміну/відновлення логіну/паролю;
- замовлення;
- покинуті перегляди та кошики;
- незавершену реєстрацію;
- передавання активності клієнта на сторінці сайту або в мобільному додатку.
Ресурс генерує подію, яка пізніше запускає сценарій для відправлення повідомлення, створення або оновлення контакту.
Використання для покинутих кошиків і переглядів
Приклад запиту:
{
"eventTypeKey": "abandoned_cart",
"keyValue": "site@com.net",
"params": [
{
"name": "email",
"value": "site@ukr.net"
},
{
"name": "items",
"value": "{\"array\":[{\"name\":\"Кондиціонер для сухого волосся\",\"price\":\"341\",\"url\":\"https://site.com/catalog/suha-dityacha-molochna-sumish-hipp-combiotic-2-750-g\",\"imageurl\":\"https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg\",\"brand\":\"Le Petit Olivier\",\"tags_weight\":\"200\",\"tags_oldprice\":\"467\"},{\"name\":\"Magnolia Nobile Парфумована вода\",\"price\":\"2341\",\"url\":\"https://site.com/catalog/suha-dityacha-molochna-sumish-hipp-combiotic-2-750-g\",\"imageurl\":\"https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg\",\"brand\":\"Acqua Di Parma\",\"tags_weight\":\"100\",\"tags_oldprice\":\"4467\"}]}"
}
]
}
Після запиту на v1/event в акаунті буде згенеровано подію, яку можна знайти у розділі “Тригери” → “Типи подій”.
Контент події можна переглянути у вкладці “Тригери” → “Історія подій” → клікнути потрібну подію у списку.
- eventTypeKey – змінна, значення якої буде назвою майбутньої події;
- keyValue – ключ події;
- params – параметри події, які можна використовувати у сценарії.
Обмежень за кількістю параметрів немає.
Обов'язковий формат – масив {"name": "email","value": "site@ukr.net"}.
Це означає, що у даних зберігається змінна email зі значенням site@ukr.net. У подальшому до неї треба звернутися у сценарії, прописавши у блоці відправлення повідомлення ${email} для успішного відправлення на пошту site@ukr.net:
Зверніть увагу на те, що контент поля items для коректного передавання необхідно серіалізувати. Цього потребує формат передавання даних, в іншому випадку JSON буде невалідним. У десеріалізованому вигляді масив має такий вигляд:
{
"array": [{
"name": "Кондиціонер для сухого волосся",
"price": "341",
"url": "https://site.com/catalog/suha-dityacha-molochna-sumish-hipp-combiotic-2-750-g",
"imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
"brand": "Le Petit Olivier",
"tags_weight": "200",
"tags_oldprice": "467"
}, {
"name": "Magnolia Nobile Парфумована вода",
"price": "2341",
"url": "https://site.com/catalog/suha-dityacha-molochna-sumish-hipp-combiotic-2-750-g",
"imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
"brand": "Acqua Di Parma",
"tags_weight": "100",
"tags_oldprice": "4467"
}]
}
Масив array містить два об'єкти (у даному випадку це два товари) з набором змінних name, price, url, imageurl, brand, tags_weight, tags_oldprice. Обмежень за кількістю масивів немає. Назви змінних можуть бути довільними.
З метою десеріалізації даних масиву array у блоці відправлення повідомлення в пункті JSON треба вказати назву поля items:
Дані із запиту можна підтягнути до повідомлення за допомогою Velocity.
Для звертання до даних можна використовувати цикл:
$!item.get('name')
$!item.get('price')
$!item.get('url')
$!item.get('imageurl')
$!item.get('brand')
$!item.get('tags_weight')
$!item.get('tags_oldprice')
Можна звертатися напряму за індексом до елементів масиву (відлік починається з 0). Такий спосіб звертання до даних може призводити до помилок підстановки контенту за відсутності елемента масиву.
Перший масив:
$!data.get('array').get(0).get('name')
$!data.get('array').get(0).get('price')
$!data.get('array').get(0).get('url')
$!data.get('array').get(0).get('imageurl')
$!data.get('array').get(0).get('brand')
$!data.get('array').get(0).get('tags_weight')
$!data.get('array').get(0).get('tags_oldprice')
Другий масив:
$!data.get('array').get(1).get('name')
$!data.get('array').get(1).get('price')
$!data.get('array').get(1).get('url')
$!data.get('array').get(1).get('imageurl')
$!data.get('array').get(1).get('brand')
$!data.get('array').get(1).get('tags_weight')
$!data.get('array').get(1).get('tags_oldprice')
І так далі.
Важливо
Звертатися до змінних слід із урахуванням регістру, оскільки змінні є регістрозалежними. Якщо в листі вказано $!item.get('ImageUrl'), а в запиті надсилається imageurl, змінну не буде підставлено. Також типовою помилкою є кириличні символи у змінних — їх треба вводити виключно латиницею.
Переглянути і перевірити підстановку динамічних даних у режимі попереднього перегляду можна за допомогою кнопки “Налаштування динамічного контенту”:
У вікні, що відкриється, в поле для введення даних треба вставити розекранований масив із динамічними даними:
Після чого натисніть кнопку "Перегляд повідомлення"
- У разі помилки під час підстановки динамічного контенту слід перевірити коректність синтаксису Velocity виразу в повідомленні.
- Якщо ви бачите помилку “Неправильний формат”, перевірте синтаксис запиту JSON.
- Якщо помилок немає, але дані не підставилися під час попереднього перегляду, перевірте, чи приведені до єдиного вигляду змінні в запиті та змінні в листі, чи коректно прописані звертання до змінних.
- Якщо помилок немає і дані підставилися, можна проводити тест, передаючи запит по API до акаунта.
Використання для створення/оновлення контакту
Приклад запиту:
{
"eventTypeKey" : "create_contact",
"keyValue" : "site@com.net",
"params": [
{
"name": "email",
"value": "site@ukr.net"
},
{
"name": "json",
"value": "{\"profileInputs\": [{\"profileInputId\":10001,\"value\":\"2020-11-23\"}]}"
}
]
}
де
- 10001 – id додаткового поля.
- 2020-11-23 – значення додаткового поля.
Контент вкладеного JSON масиву або об'єкта також підлягає серіалізації.
Зверніть увагу на коректність даних, що передаються:
- довжина імені та прізвища (до 60 символів);
- коректний номер телефону в міжнародному форматі: (+380501348460);
- значення додаткового поля контакту, яке відповідає його формату.
У разі некоректного передавання даних весь масив для оновлення полів контакту буде проігнорований системою і додавання даних до картки контакту не буде здійснено.
Для коректної роботи сценарію в блоках "Створити контакт"/"Оновити контакт" необхідно в полі EmailAddress прописати змінну із запиту – ${email}, а в полі JSON – масив для створення/оновлення контакту – ${json}.
Детальний опис блоку “Завдання” для створення та оновлення контакту ви знайдете в цьому гайді.
Використання для відправлення сервісних листів
Розглянемо на прикладі запуску листа про відновлення пароля.
Приклад запиту:
{
"eventTypeKey": "password_recovery",
"keyValue": "site@com.net",
"params": [{
"name": "EmailAddress",
"value": "site@ukr.net"
},
{
"name": "password",
"value": "12345678"
}
]
}
У сценарії необхідно використовувати блок "Завдання" - "Обов'язковий емейл", а в листі, який буде надіслано, вказати змінну $!data.get('password')
Детальний опис блоку “Завдання” ви знайдете в цьому гайді.
Крім того, що ресурс v1/event можна використовувати для створення/оновлення контакту і запуску сценарію з можливістю підстановки динамічного контенту до тіла повідомлення, цей ресурс може бути задіяний для передавання замовлень до системи. Цьому питанню присвячена тематична стаття.