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

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

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

Ви можете використовувати цей 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')

І так далі.

Переглянути та перевірити підставляння динамічних даних у режимі попереднього перегляду можна за допомогою кнопки “Налаштування динамічного контенту”:

У вікні що відкриється, в полі для введення даних треба вставити масив із динамічними даними:

Після чого натисніть кнопку "Перегляд повідомлення"

• У разі помилки під час підставляння динамічного контенту слід перевірити коректність синтаксису 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')

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

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

Ви можете перевірити дані контактів у подіях, використовуючи метод 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"
    }
    ]    
}

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