Использование 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": "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')

И так далее.

Важно!

Обращаться к переменным нужно с учетом регистра, так как переменные регистрозависимы. Если в письме указана $!item.get('ImageUrl'), а в запросе передается imageurl, переменная не подставится. Также, частая ошибка — кириллические символы в переменных, необходимо вводить переменные только латиницей.

Просмотреть и проверить подстановку динамических данных на предпросмотре можно с помощью кнопки “Настройки динамического контента”:

Подстановка динамического контента

В открывшемся окне в поле для ввода данных нужно вставить массив с динамическими данными:

Ввод массива данных

Далее нажмите кнопку "Просмотр сообщения"

  • В случае ошибки при подстановке динамического контента, необходимо удостовериться в корректности синтаксиса 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 символов),
  • корректный номер телефона в международном формате: (+380001348460.),
  • значение дополнительного поля контакта, соответствующее его формату.

В случае некорректно передаваемых данных весь массив для обновления полей контакта будет проигнорирован системой и добавление данных в карточку контакта не произойдет.

Для корректной работы сценария в блоках “Создать контакт”/”Обновить контакт” необходимо в поле 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')

Сценарий для восстановления пароля

Подробное описание блока  “Задача” описано в этом руководстве.

Использование для проверки данных контактов в событиях

Вы можете проверить данные контактов в событиях, используя метод 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