Використання API-ресурсу event

Дані користувача

Email

Омніканальність

Автоматизація

Відстеження подій та поведінки

Використання API-ресурсу Generate event

Використовуючи API ресурс Generate event, ви можете надсилати події зі свого вебсайту та зберігати їх у нашій системі. Ці події можна використовувати для запуску сценарію або для сегментації.

Важливо

Методи API версії 2 не потребують екранування вкладеного JSON.

Метод включає параметри, які описані в наступній таблиці.

Зверніть увагу

Максимальний розмір контенту для подій, що надсилаються в тілі запиту, становить 20 кілобайтів. Зверніться до служби підтримки, якщо вам потрібно змінити максимальний розмір.

Параметр Тип Опис
eventTypeKey рядок, обов'язковий Ключ ідентифікатора типу події. Якщо типу події з таким ключем не існує, створюється новий.
Допускається використання всіх символів, крім < ; ’ \ / | " ` ' ^ ? ! , >
Максимальна кількість символів: 100
keyValue рядок

Ключ події. Визначає унікальність події.

Ключ має містити унікальне значення для кожного контакту (наприклад, адреса електронної пошти, номер телефону, зовнішній ідентифікатор контакту тощо).
Якщо цей параметр не вказаний, params повинні містити один із наступних ідентифікаторів контакту:

  • contactId
  • externalCustomerId (див. примітку нижче)
  • email
  • phone
  • pushToken: для веб або мобільних пуш-повідомлень
Допускається використання всіх символів, крім < ; ’ \ / | " ` ' ^ ? ! , >
Максимальна кількість символів: 300
params масив об'єктів Список параметрів події, представлений у вигляді масиву пар "ключ" - "значення". Ключі параметрів довільні.
Використовується у сценаріях та для створення динамічного контенту у повідомленнях.

Важливо

При передачі подій за допомогою методу Generate event v2 externalCustomerId в params ігнорується, якщо він містить порожнє або null значення. Наприклад, "", " ", " ", "null", null.

Ви можете використовувати цей API ресурс для надсилання наступних запитів, як описано нижче.

Використання для покинутих кошиків і переглядів

Приклад запиту:

{
    "eventTypeKey": "abandoned_cart",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "emailAddress",
            "value": "site@ukr.net"
        },
        {
            "name": "items",
            "value":
            {
                "array":
                [
                    {
                        "name": "Кондиціонер для сухого волосся",
                        "price": "341",
                        "url": "https://site.com/catalog/suhaya-detskaya-molochnaya-smes-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/suhaya-detskaya-molochnaya-smes-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"
                    }
                ]
            }
        }
    ]
}

eventTypeKey – це рядковий ідентифікатор типу події. Якщо до цього його не існувало, після першого запиту він з'явиться в обліковому записі, і його можна буде побачити в розділі “Тригери” → “Типи подій”.

Редагування події

Параметри події можна переглянути у вкладці “Тригери” → “Історія подій” → клікнути потрібну подію у списку.

Перегляд історії подій

  • keyValue – ключ події;
  • params – параметри події, які можна використовувати у повідомленні та сценарії.

Обмежень за кількістю параметрів немає.

Обов'язковий формат – масив {"name": "emailAddress","value": "site@ukr.net"}.

Це означає, що у даних зберігається змінна email зі значенням site@ukr.net. Надалі до неї треба звернутися у сценарії, прописавши у блоці відправлення повідомлення ${emailAddress} для успішного відправлення на пошту site@ukr.net:

Створення сценарію

Масив array містить два елементи (у цьому випадку це два товари) з набором змінних name, price, url, imageurl, brand, tags_weight, tags_oldprice. Обмежень за кількістю елементів немає. Назви змінних можуть бути довільними.

З метою використання у повідомленні даних з масиву array у блоці відправлення повідомлення в пункті JSON треба вказати назву поля items:

Заповнення пунктів налаштувань

Дані з події можна підставити повідомлення за допомогою velocity-конструкцій.

Для звертання до даних можна використовувати цикл:

#foreach($!item in $!data.get('array'))
$!item.get('name')
$!item.get('price')
$!item.get('url')
$!item.get('imageurl')
$!item.get('brand')
$!item.get('tags_weight')
$!item.get('tags_oldprice')
#end

Можна звертатися напряму за індексом до елементів масиву (відлік починається з 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": "emailAdddress",
            "value": "site@ukr.net"
        },
        {
            "name": "phone",
            "value": "380501234567"
        },
        {
            "name": "externalCustomerId",
            "value": "AV13760"
        },
        {
            "name": "json",
            "value":
            {
                "profileInputs":
                [
                    {
                        "profileInputId": 10001,
                        "value": "2020-11-23"
                    }
                ]
            }
        }
    ]
}

де

  • 10001 – id додаткового поля.
  • 2020-11-23 – значення додаткового поля.

Зверніть увагу на коректність даних, що передаються:

  • Довжина імені та прізвища – максимум 60 символів.
  • Коректний номер телефону в міжнародному форматі. Наприклад, +380001348460.
  • Значення додаткового поля контакту, яке відповідає його формату.

У разі некоректного передавання даних, весь масив для оновлення полів контакту буде проігнорований системою і додавання даних до картки контакту не буде здійснено.

Для коректної роботи сценарію в блоках "Створити контакт"/"Оновити контакт" необхідно в полі Email прописати змінну із запиту – ${emailAddress}, а в полі JSON – масив для створення/оновлення контакту – ${json}.

Підстановка змінних

Детальний опис блоку “Задача” для створення та оновлення контакту ви знайдете в цій інструкції.

Використання для відправлення сервісних листів

Розглянемо на прикладі запуску листа про відновлення пароля. 

Приклад запиту:

{
"eventTypeKey": "password_recovery",
"keyValue": "site@com.net",
"params": [{
"name": "EmailAddress",
"value": "site@ukr.net"
},
{
"name": "password",
"value": "12345678"
}
]
}

У сценарії необхідно використовувати блок "Задача" - "Обов'язковий email", а в листі, який буде надіслано, вказати змінну $!data.get('password')

Сценарій Welcome-розсилки

Детальний опис блоку “Задача” ви знайдете в цій інструкції.

Використання для перевірки даних контактів у подіях

Ви можете перевірити дані контактів у подіях, використовуючи метод Generate event.

Вкажіть contactJson у params як значення параметра name.

{
  "params": [
    {
      "name": "contactJson",
      "value": "..."
    }
  ]
}

Вкажіть дані, які ви хочете перевірити, у полі value.

Наприклад:

{"firstname":"...","lastname":"...","sms":"...","town":"...","timeZone":"Etc/GMT+03","languageCode":"uk","profileInputs":
[{"profileInputId":10001,"value":"..."}],"confirmed":false}

Коли ви надсилаєте цей запит, використовуючи метод Generate event, API-ресурс розуміє це як отримання нового контакту і виконує перевірку даних.

Якщо дані є недійсними, метод повертає відповідь “400 Bad Request”. Відповідь містить неприпустимі поля та відомості про помилку.

Крім того, що ресурс Generate event можна використовувати для створення/оновлення контакту і запуску сценарію з можливістю підставляння динамічного контенту до тіла повідомлення. Цей ресурс можна використовувати для передачі замовлень до системи. Цьому питанню присвячена тематична стаття.

Збагачення профілю контакту даними про місцеперебування за IP в події

Використовуючи метод Generate event v2, можна розширити параметри події, передавши IP-адресу контакту в params. IP-адреса має бути у форматі IPv4 або IPv6.

Приклад запиту:

{
  "keyValue": "john.doe@example.com",
  "eventTypeKey": "welcome",
  "params": [
    {
      "name": "email",
      "value": "john.doe@example.com"
    },
    { "name": "ip",
      "value": "192.0.2.1"
    }
    ]    
}

Подію буде доповнено параметрами, описаними в таблиці.

Параметр Опис
countryCode Дволітерний код країни
countryId Ідентифікатор країни у географічній базі даних
regionName Назва регіону англійською
regionId Ідентифікатор регіону у географічній базі даних
cityName Назва міста англійською
cityId Ідентифікатор міста у географічній базі даних

Історія подій

Зверніть увагу

Якщо система не може визначити регіон та місто по IP, вона визначає країну за параметром події countryCode.

Локація

Зверніть увагу

Якщо подія вже містить один з наступних параметрів, додаткові поля не створюються і місцеперебування залишається незмінним:

  • countryCode,
  • countryId,
  • regionName,
  • regionId,
  • cityName,
  • cityId
Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email