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

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

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

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