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

Універсальний ресурс Generate 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/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": "email","value": "site@ukr.net"}.

Це означає, що у даних зберігається змінна email зі значенням site@ukr.net. Надалі до неї треба звернутися у сценарії, прописавши у блоці відправлення повідомлення ${email} для успішного відправлення на пошту 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": "email",
            "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 символів);
• коректний номер телефону в міжнародному форматі: (+380501348460);
• значення додаткового поля контакту, яке відповідає його формату.

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

Для коректної роботи сценарію в блоках "Створити контакт"/"Оновити контакт" необхідно в полі EmailAddress прописати змінну із запиту – ${email}, а в полі 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 можна використовувати для створення/оновлення контакту і запуску сценарію з можливістю підставляння динамічного контенту до тіла повідомлення, цей ресурс можна використовувати для передавання замовлень до системи. Цьому питанню присвячена тематична стаття.