Использование API-ресурса Generate event

Используя API ресурс Generate event, вы можете отправлять события со своего веб-сайта и сохранять их в нашей системе. Эти события можно использовать для запуска сценария или сегментации.

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

Этот 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"
                    }
                ]
            }
        }
    ]
}
JSON
COPY
MORE

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
Apache
COPY

Можно обращаться напрямую по индексу к элементам массива (счет начинается с 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')
Apache
COPY

Второй элемент:

$!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')
Apache
COPY

И так далее.

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

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

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

• В случае ошибки при подстановке динамического контента, необходимо удостовериться в корректности синтаксиса 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"
                    }
                ]
            }
        }
    ]
}
JSON
COPY
MORE

где

• 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"
		}
	]
}
JSON
COPY

В сценарии необходимо использовать блок "Задача" - "Обязательный емейл", а в письме, которое будет отправляться, указать переменную $!data.get('password')

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

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

Вы можете проверить данные контактов в событиях, используя метод Generate event.

Установите значение contactJson в params в качестве параметра name.

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

Укажите данные, которые вы хотите проверить, в поле value.

Например:

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

Когда вы отправляете этот запрос, используя метод 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"
    }
    ]    
}
JSON
COPY

Событие будет дополнено параметрами, описанными в следующей таблице.

Обогащенное событие использует местоположение контакта в сценарии.

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