Инструкция для разработчиков: как настроить передачу данных с сайта
Модуль Продажи предназначен для отправки коммуникаций (email, пуши, смс и т.д.), сопровождающих процессы выбора и покупки товаров и услуг — например, в интернет-магазинах, но не ограничиваясь ими.
В качестве исходных данных для настройки сценариев коммуникаций используется информация о параметрах продаваемых товаров и услуг и данные о действиях покупателя на сайте клиента (события).
Модуль работает на основе поступающих в Sendsay событий о действиях пользователя и генерации собственных событий на базе полученных данных.
Отправка событий на базе еcоmmеrсe-событий Google Analytics и Яндекс Метрики
Настройка модуля
Список клиентских ssec-событий
ID | Константа события | Событие | Область в stat.uni |
---|---|---|---|
0 | VIEW_PRODUCT | Просмотр карточки товара | ssec_product_view |
1 | ORDER | Заказ | ssec_order |
2 | VIEW_CATEGORY | Просмотр категории товара | ssec_category_view |
3 | BASKET_ADD | Добавление товаров в корзину | ssec_basket |
4 | BASKET_CLEAR | Очистка корзины | ssec_basket_clear |
5 | SEARCH_PRODUCT | Поиск товара | ssec_product_search |
6 | SUBSCRIBE_PRODUCT_PRICE | Подписка на изменение стоимости товара | ssec_product_price |
7 | SUBSCRIBE_PRODUCT_ISA | Подписка на пинг о появлении товара в продаже | ssec_product_isa |
8 | FAVORITE | Добавление товара в избранное | ssec_product_favorite |
12 | PREORDER | Предварительный заказ | ssec_product_preorder |
13 | PRODUCT_ISA | Товар появился | |
15 | PRODUCT_PRICE_CHANGED | Стоимость товара изменилась | |
28 | REGISTRATION | Регистрация на сайте | |
29 | AUTHORIZATION | Авторизация на сайте |
Набор доступных полей
Имя поля при внесении (JS & API) | Имя поля в stat.uni | Тип значения | Доступность | Аналог в YML |
---|---|---|---|---|
id | product.id | String | ||
name | product.name | String | ||
picture | product.picture | Array(String) (абсолютная ссылка) | ||
url | product.url | String (абсолютная ссылка) | ||
available | product.available | UInt8 | ||
category_paths | product.category_paths | Array(String) | ||
category_id | product.category_id | Int64 | ||
description | product.description | String | ||
vendor | product.vendor | String | ||
model | product.model | String | ||
type | product.type | String | ||
price | product.price | Nullable(Decimal64(2)) | ||
old_price | product.old_price | Nullable(Decimal64(2)) | ||
category | category | String | ||
transaction_id | transaction.id | String | Заказ, корзина | |
delivery_dt | delivery.dt | DateTime | Заказ | |
delivery_price | delivery.price | Nullable(Decimal64(2)) | Заказ | |
payment_dt | payment.dt | DateTime | Заказ | |
transaction_dt | transaction.dt | DateTime | Заказ, корзина | |
transaction_status | transaction.status | Int64 DEFAULT 0 | Заказ, корзина | |
transaction_discount | transaction.discount | Nullable(Decimal64(2)) | Заказ, корзина | |
transaction_sum | transaction.sum | Nullable(Decimal64(2)) | Заказ, корзина | |
cp1…cp20 | cp1…cp20 | String |
Статусы заказа
ID | Статус |
---|---|
1 | Заказ Оформлен (создан,принят) |
2 | Заказ Оплачен |
3 | Заказ Принят в работу (сборка, комплектация) |
4 | Доставка |
5 | Доставка: присвоен трек-номер |
6 | Доставка: передан в доставку |
7 | Доставка: отправлен |
8 | Доставка: поступил в пункт-выдачи / передан курьеру |
9 | Доставка: получен |
10 | Заказ Отменен: отмена заказа |
11 | Заказ Отменен: возврат заказа |
12 | Заказ Изменен: обновление заказа |
Структура ssec-события
Ssec-события всегда передаются в Sendsay как массив объектов. Если вам надо передать одно событие, то это будет массив с одним объектом.
[
{
"id": "product1", //обязательно
"description": "description",
"available": 1 | 0,
"model": "model",
"name": "name",
"old_price": 5.99,
"picture": [""],
"price": 7.88,
"url": "url",
"vendor": "vendor",
"event_type": 1,
"event_site": 1
...
}
]
Так как в заказе или корзине может быть более одного товара, то структура передачи к нам таких событий отличается от стандартной. Это все так же массив объектов, но все сведения о товарах содержатся в массиве items
:
[
{
"transaction_id": "x1", //обязательно
"transaction_dt": "2022-07-25 23:25:13", //обязательно для заказа
"transaction_sum": 100.9, //желательно
"payment_dt": "2022-07-25 23:25:13", //необязательно
"delivery_dt": "2022-07-25 23:25:13", //необязательно
"update": 1 | 0, //необязательно
"items": [ //обязательно при update != 1
{
"id": "product1", //обязательно
"qnt": 2, //обязательно
"price": 5.88 //обязательно
}
]
}
]
Персонализация первичного ключа товара для корзины и заказа
Если вам нужно передавать в корзину (заказ) разные товары с одним и тем же product.id (например, что-то с разным размером или объемом), то вам нужно передать дополнительный параметр для создания нового первичного ключа, отличного от product.id.
В принимаемых данных о товаре мы ожидаем поле uniq
, в значении которого должно передаваться имя поля с дополнением для нового первичного ключа.
Поле uniq
- необязательно, при его отсутствии в качестве первичного ключа используется значение product.id.
(window['sndsyApiOnReady'] = window['sndsyApiOnReady'] || []).push(function () {
sndsyApi.ssecEvent(
'BASKET_ADD',
[
{
"transaction_sum": 100.9, //желательно
"items": [ //обязательно
{
"id": "3457", //обязательно
"qnt": 2, //обязательно
"price": 5.88, //обязательно
"name": "iPhone",
"uniq": "name"
},
{
"id": "3457", //обязательно
"qnt": 2, //обязательно
"price": 5.88, //обязательно
"name": "Pixel",
"uniq": "name"
},
{
"id": "3456", //обязательно
"qnt": 2, //обязательно
"price": 5.88, //обязательно
"name": "iPhone"
}
]
}
],
{ email: 'АДРЕС КЛИЕНТА' } //необязательно, при отсутствии email будет распознаваться нашим скриптом
);
});
typeof sndsyApi != 'undefined' && sndsyApi.runQueue();
Для для двух товаров с "id" == 3457
& "uniq" == "name"
значение первичных ключей будет "3457/iPhone"
& "3457/Pixel"
.
Для товара с "id" == 3456
и без поля uniq
значение певичного ключа будет "3456"
Добавление событий через JS-cкрипт
Все события могут быть переданы в Sendsay с вашего сайта через вызов соответствующей JS-функции.
Идентификатор пользователя, которому должно добавиться событие вы можете передать самостоятельно в опциональном параметр е, либо довериться нашему скрипту.
В случае если пользователя определяет наш скрипт, то вместе с идентификатором (email, web-push, umid) придет информация о выпуске, из которого пользователь перешел на сайт.
JavaScript-синтаксис
Размещение кода напрямую в HTML-странице:
<script type="text/javascript">
(window["sndsyApiOnReady"] = window["sndsyApiOnReady"] || []).push(function() {
sndsyApi.ssecEvent(<event_type>, <[ items_array ]>, { email: 'name@domain.ru' });
});typeof sndsyApi != 'undefined' && sndsyApi.runQueue();
</script>
Также вы можете вызывать функцию sndsyApi.ssecEvent()
в нужный вам момент из любого места вашего JS-кода.
Изменение анкетных данных контакта через JS-функции добавления событий
Одновременно с передачей любых событий можно добавлять, изменять, удалять анкетные данные контакта, для которого вы передаете событие.
(window['sndsyApiOnReady'] = window['sndsyApiOnReady'] || []).push(function () {
sndsyApi.ssecEvent(
'REGISTRATION',
{
email: 'АДРЕС КЛИЕНТА',
extra: { // любые данные которые будут включены в корень запроса
dk: [["base.name","set","Andrey"]] // анкетные данные
}
}
);
});
typeof sndsyApi != 'undefined' && sndsyApi.runQueue();
Формат параметра dk:
[
[ "base.name", "set", "Vladimir"],
[ "client_data.pets", "push", [{"pet_type":"dog","age":1}]],
[ "client_data", "merge", {"type":"GOLD","orders_count":55,"prefered_item":"shopping bag"}]
]
Полное описание возможностей работы с данными и режимов можно найти в документации АПИ.
Добавление данных через Sendsay API
Все события можно добавлять, используя Sendsay API. Это будет полезно для добавления или обновления данных о совершенных заказах, а также при добавлении событий, которые не относятся к действиям ваших клиентов, например «появление товара в продаже» или «изменение стоимости товара».
Для отправки событий модуля "Продажи" используется отдельный эндпоинт:
https://ssec.sendsay.ru/general/ssec/v100/json/ACCOUNT_ID
ACCOUNT_ID надо заменить идентификатор (логин) вашего аккаунта Sendsay (не email).
Пример API-запроса:
curl --location --request POST 'https://ssec.sendsay.ru/general/ssec/v100/json/ACCOUNT_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: sendsay apikey=API_KEY' \
--data-raw '[
{
"email": "АДРЕС_ПОДПИСЧИКА",
"addr_type": "email",
"transaction_id": "x1",
"transaction_dt": "2022-07-25 23:25:13",
"transaction_sum": 11.98,
"transaction_discount": 1.59,
"transaction_status": 1,
"items": [
{
"id": 50,
"name": "Artefact 1.9",
"price": 5.99,
"qnt": 2
},
{
"id": 52,
"name": "Renegat 12.1",
"price": 7.65,
"qnt": 2
}
],
"event_type": 1,
"update": 1
}
]'