Передача даних про поведінку відвідувачів сайту через REST API
Ви можете передавати до eSputnik події, щоб:
- точніше вибирати товари для покинутих кошиків і переглядів,
- пропонувати рекомендації на сторінках оформлення замовлення,
- управляти аудиторіями користувачів та ін.
Події можна відправляти до системи двома способами:
- Через браузер, викликаючи функцію eS.JS.
- З бекенда, використовуючи REST API.
У цій інструкції ми детально розглянемо другий варіант.
Важливо
При налаштуванні трекінгу через REST API функціонал рекомендацій на сайті буде недоступний; у цьому випадку треба використовувати варіант виклику функцій eS.JS
Заголовки запиту
POST / HTTP/1.1 Host: https://tracker.esputnik.com/api/v2 Content-type: application/json |
Код відповіді 200. Авторизація не потрібна.
ProductPage
Опис
Для якісного ранжування товарів/категорій або для відправлення тригерів за покинутими переглядами необхідно надіслати запит, у якому буде вказано:
- яку картку товару на поточний момент переглядає користувач,
- ціну та наявність товару.
Приклад
{ "GeneralInfo": { "eventName": "ProductPage", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "ProductPage": { "Product": { "productKey": "72354", "price": "754 USD", "isInStock": "1", "tag_something": [ "abc", "bca" ] }, "Tags": { "some_tags": [ "some_tag1", "some_tag2" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов’язковий Тип: Object | Загальна інформація |
eventName | “ProductPage” Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Тип: String | Email користувача |
user_name | "Gregori Boczynski" Тип: String | Ім'я та прізвище користувача |
user_es_contact_id | "255830499" Тип: String | ID клієнта в базі eSputnik |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" Тип: Object String | Cookie sc – це cookie, згенерована нашим скриптом, якщо він встановлений на вашому сайті. Кожна cookie має бути унікальною для кожного користувача. Ви можете створювати cookie власноруч. Приклад виклику цієї cookie із javascript document.cookie, потрібна нам cookie має ім'я “sc” |
datetime | 1579622183208 | Timestamp (millisecond) |
ProductPage | Обов'язковий Тип: Object | Опис події |
productKey | “72354” Тип: String |
|
price | “754 USD” Тип: String |
|
isInStock | “1” Тип: Int |
|
tag_[something] | ["abc","bca"] Тип: Array of Strings |
|
Tags | Необов'язковий Тип: Object | Додаткові поля |
StatusCart
Опис
Подія, що відправляється в момент зміни кошика (з новим GUID), наприклад на картці товару або сторінці категорій за кнопкою “Купити”. Кошик має оновлюватися з усіх сторінок. Якщо кошик порожній, то необхідно відправити порожній кошик (порожній масив без товарів).
Приклад
{ "GeneralInfo": { "eventName": "StatusCart", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "StatusCart": { "GUID": "6F9619FF-8B86-D011-B42D-00CF4FC964FF", "Products": [ { "productKey": "430738", "price": 201.95, "discount": 180, "quantity": 1, "price_currency_code": "UAH", "tag_something": [ "aaa", "bbb" ] }, { "productKey": "902339", "price": 596, "discount": 590, "quantity": 1, "price_currency_code": "UAH", "tag_something": [ "aaa", "bbb" ] } ], "Tags": { "some_tags": [ "1", "a2" ], "some_tags1": [ "4", "gg" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Object String | Загальна інформація |
eventName | “StatusCart” Обов'язковий Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Обов'язковий Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Необов'язковий Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Необов'язковий Тип: String | Email користувача |
user_name | "Gregori Boczynski" Необов'язковий Тип: String | Ім'я/Прізвище користувача |
user_es_contact_id | "255830499" Необов'язковий Тип: String | ID клієнта в базі eSputnik |
datetime | 1579622183208 | Timestamp (millisecond) |
GUID | “6F9619FF-8B86-D011-B42D-00CF4FC964FF” Обов'язковий Тип: String |
|
StatusCart | Обов'язковий Тип: Object String |
|
productKey | “430738” Обов'язковий Тип: String |
|
price | “201.95” Обов'язковий Тип: String | Ціна за одиницю товару |
discount | “180” Необов'язковий Тип: String | Знижкова ціна за одиницю товару |
quantity | “1” Обов'язковий Тип: Int | Кількість товарів |
price_currency_code | "UAH" Необов'язковий Тип: String | Позначення грошової валюти |
tag_[something] | ["abc","bca"] Необов'язковий Тип: Array of Strings |
|
Tags | Необов'язковий Тип: Object | Додаткові поля |
Wishlist
Опис
Надсилання події AddToWishlist - у момент додавання товару до списку бажаного (вибране).
Необхідна для розрахунку та виведення рекомендацій та надсилання тригерів, пов'язаних зі списком бажань.
Приклад
{ "GeneralInfo": { "eventName": "AddToWishlist", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "AddToWishlist": { "Product": { "productKey": "72354", "price": "754", "isInStock": "1", "tag_something": [ "abc", "bca" ] }, "Tags": { "some_tags": [ "some_tag1", "some_tag2" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Object String | Загальна інформація |
eventName | “AddToWishlist” Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Тип: String | Email користувача |
user_name | "Gregori Boczynski" Тип: String | Ім'я/Прізвище користувача |
user_es_contact_id | "255830499" Тип: String | ID клієнта в базі eSputnik |
datetime | 1579622183208 | Timestamp (millisecond) |
AddToWishlist | Обов'язковий Тип: Object String |
|
productKey | “430738” Тип: String |
|
price | “201.95” Тип: String | Ціна за одиницю товару |
tag_[something] | ["abc","bca"] Тип: Array of Strings |
|
Tags | Необов'язковий Тип: Object | Додаткові поля |
PurchasedItems
Опис
Для виведення рекомендацій на сторінці підтвердження замовлення або для відправлення тригерів за покинутими кошиками треба відправити запит, у якому буде зазначено, який товар придбав користувач.
Приклад
{ "GeneralInfo": { "eventName": "PurchasedItems", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "PurchasedItems": { "Products": [ { "product_id": "430738", "unit_price": "201.95", "quantity": 1 }, { "product_id": "211452", "unit_price": "341.80", "quantity": 2 } ], "OrderNumber": "123/2017", "Tags": { "some_tags1": [ "4", "gg" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Object String | Загальна інформація |
eventName | “StatusCart” Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Тип: String | Номер телефону в міжнародному форматі |
user_email
| "user@mail.com" Тип: String | Email користувача |
user_es_contact_id | "255830499" Тип: String | ID клієнта в базі eSputnik |
user_name | "Gregori Boczynski" Тип: String | Ім'я/Прізвище користувача |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" Тип: Object String | Cookie sc – це cookie, згенерована нашим скриптом, якщо він встановлений на вашому сайті. Кожна cookie має бути унікальною для кожного користувача. Ви можете створювати cookie власноруч. Приклад виклику цієї cookie із javascript document.cookie, потрібна нам cookie має ім'я “sc” |
OrderNumber | “123/2017” Тип: String |
|
PurchasedItems | Тип: Array of Strings | Перелік товарів |
product_id | “430738” Тип: String |
|
unit_price | “201.95” Тип: String | Ціна за одиницю товару |
quantity | “1” Тип: Integer | Кількість товарів |
Tags | Необов'язковий Тип: Object | Додаткові поля |
ProductImpressions
Опис
ProductImpressions — подія, відправлення якої дозволяє відстежувати покази блоків. За замовчуванням відправляється скриптом, по JS API. Додатково передавати не потрібно. Якщо скрипт не встановлено, передавати згідно формату.
Приклад
{ "GeneralInfo": { "eventName": "ProductImpressions", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "ProductImpression": { "Products": [ { "product_id": "430968", "container_type": "1253" }, { "product_id": "430738", "container_type": "1254" }, { "product_id": "429983", "container_type": "1255" } ], "Tags": { "some_tags": [ "1", "a2" ], "some_tags1": [ "4", "gg" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Array of Objects | Загальна інформація |
eventName | “ProductImpressions” Обов'язковий Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Обов'язковий Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Необов'язковий Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Необов'язковий Тип: String | Email користувача |
user_es_contact_id | "255830499" Необов'язковий Тип: String | ID клієнта в базі eSputnik |
user_name | "Gregori Boczynski" Необов'язковий Тип: String | Імя/Прізвище користувача |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обов'язковий Тип: Оbject String | Cookie sc – це cookie, згенерована нашим скриптом, якщо він встановлений на вашому сайті. Кожна cookie має бути унікальною для кожного користувача. Ви можете створювати cookie власноруч. Приклад виклику цієї cookie із javascript document.cookie, потрібна нам cookie має ім'я “sc” |
ProductImpression | Обов'язковий Тип: Array of Objects |
|
product_id | “430968” Обов'язковий Тип: String | Ідентифікатор товару чи категорії, який є у фіді |
container_type | “1253” Обов'язковий Тип: String | Номер блоку рекомендацій. Отримати container_type можна у відповідь на запит рекомендацій. |
Tags | Необов'язковий Тип: Object | Додаткові поля |
CategoryPage
Опис
Можливе використання:
- для тригерів,
- перегляду сайту з відвідуванням категорії, без відвідування картки товарів,
- перегляду сайту без будь-якого відвідування категорії/товару.
Необхідно надіслати запит, у якому буде вказано, на якій категорії знаходиться користувач.
Приклад
{ "GeneralInfo": { "eventName": "CategoryPage", "siteId": "8A412DC", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "user@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "255830499", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "CategoryPage": { "Category": { "categoryKey": "509876" }, "Tags": { "some_tags": [ "1", "a2" ], "some_tags1": [ "4", "gg" ] } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Object | Загальна інформація |
eventName | “ProductPage” Обов'язковий Тип: String | Назва події, що відправляється |
siteId | “8A412DC” Обов'язковий Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Необов'язковий Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Необов'язковий Тип: String | Email користувача |
user_es_contact_id | "255830499" Необов'язковий Тип: String | ID клієнта в базі eSputnik |
user_name | "Gregori Boczynski" Необов'язковий Тип: String | Ім’я та Прізвище користувача |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обов'язковий Тип: Object String | Cookie sc – це cookie, згенерована нашим скриптом, якщо він встановлений на вашому сайті. Кожна cookie має бути унікальною для кожного користувача. Ви можете створювати cookie власноруч. Приклад виклику цієї cookie із javascript document.cookie, потрібна нам cookie має ім'я “sc” |
datetime | 1579622183208 | Timestamp (millisecond) |
CategoryPage | Обов'язковий Тип: Object | Опис події |
categoryKey | “509876” Обов'язковий Тип: String | Назва або ID категорії згідно фіду товарних даних |
Tags | Необов'язковий Тип: Object | Додаткові поля |
CustomerData
Опис
Для відправлення тригерів за покинутими кошиками та покинутими переглядами необхідно надіслати запит, у якому буде вказана інформація про користувача.
Email має відправлятися як мінімум у персональному кабінеті, на сторінці "Дякуємо за замовлення" та під час реєстрації.
Приклад
{ "GeneralInfo": { "eventName": "CustomerData", "siteId": "8D3869C", "datetime":1579622183208, "externalCustomerId": "1234509876", "user_phone": "3801111111111", "user_email": "user@mail.com", "user_es_contact_id": "255830499", "user_name": "Johny", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3CGGG1" } } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
GeneralInfo | Обов'язковий Тип: Array of Objects | Загальна інформація |
eventName | “StatusCart” Тип: String | Назва події, що відправляється |
siteId | “8D3869C” Тип: String |
|
externalCustomerId | "1234509876" Необов'язковий Тип: String | Зовнішній ідентифікатор контакту |
user_phone | "1-541-754-3010" Тип: String | Номер телефону в міжнародному форматі |
user_email | "user@mail.com" Тип: String | Email користувача |
user_es_contact_id | "255830499" Тип: String | ID клієнта в базі eSputnik |
user_name | "Gregori Boczynski" Тип: String | Ім’я/Прізвище користувача |
datetime | 1579622183208 | Timestamp (millisecond) |
cookies | "CDA68358-94FB-4D83-9655-3FEB3C4114A3" Тип: Object String | Cookie sc – це cookie, згенерована нашим скриптом, якщо він встановлений на вашому сайті. Кожна cookie має бути унікальною для кожного користувача. Ви можете створювати cookie власноруч. Приклад виклику цієї cookie із javascript document.cookie, потрібна нам cookie має ім'я “sc” |
SearchRequest
Опис
Для збору статистики за пошуковими запитами необхідно надіслати значення зі строки пошуку.
Ця подія використовується для тригерів. Її потрібно надсилати лише у випадку, коли пошук не дав результатів. У тригері такі контакти отримуватимуть персональні рекомендації (на даний момент, видача рекомендацій не залежить від значення, введеного в пошуку, підтримка цієї функції передбачається в майбутньому).
Приклад
{ "GeneralInfo": { "eventName": "SearchRequest", "siteId": "CE460EC", "datetime": 1668792552000, "externalCustomerId": "1234509876", "user_phone": "1-541-754-3010", "user_email": "userdech123@mail.com", "user_name": "Gregori Boczynski", "user_es_contact_id": "", "cookies": { "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3" } }, "SearchRequest": { "search": "input_value", "isFound": 1 } }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
search | "Coffe" | Значення зі строки пошуку. Те, що шукаємо на сайті. |
isFound | 1/0 Необовʼязковий Тип: Int | Якщо список пустий, повертається 0, якщо є дані - 1. |
ProductUpdate
Опис
ProductUpdate — опціональна подія, яка в режимі реального часу актуалізує дані про товари в eSputnik незалежно від планового оновлення фіду. Передавайте в події ті властивості товарів, які потребують постійного оновлення, — ціна, знижка, наявність тощо.
Приклад
{ "GeneralInfo": { "eventName": "ProductUpdate", "siteId": "site_id" }, "ProductUpdate": [ { "brand": "Apple", "name": "iPhone 7", "description": "Some description", "product_id": "430738", "imgurl": "https://domain.com/apple/product_large.png", "url": "https://domain.com/apple/product_page_example.html", "unit_price": "201.95", "isInStock": "1", "tag_discount": ["10"], "tag_oldprice": ["224.38"], "price_currency_code": "UAH", "category_id": ["3"], "tag_something": [ "aaa", "bbb" ] }, { "brand": "Apple", "name": "iPhone 7", "description": "Some description", "product_id": "430738", "imgurl": "https://domain.com/apple/product_large.png", "unit_price": "201.95", "isInStock": "1", "tag_discount": ["10"], "tag_oldprice": ["224.38"], "price_currency_code": "UAH", "category": "level1 > level2 > level3", "category_id": ["1", "2", "3"], "tag_something": [ "aaa", "bbb" ] } ] }
JSON
Параметри
Назва | Приклад | Опис |
---|---|---|
ProductUpdate | Тип: Object Обов’язковий | Масив оновлених товарів та їх параметрів |
siteId | site_id Обов’язковий Тип: String | Назва сайту |
product_id | 430738 Обов’язковий Тип: Int | Ідентифікатор товару |
isInStock | 1 Обов’язковий, може бути 0 або 1 Тип: Int |
|
unit_price | 201.95 Необовʼязковий Тип: Int | Ціна за одиницю |
description | Some description Необовʼязковий Тип: String | Опис товару |
name | iPhone 7 Необовʼязковий Тип: String | Назва товару |
imgurl | https://domain.com/apple/product_large.png Необовʼязковий Тип: String | URL зображення товару |
url | https://domain.com/apple/product_page_example.html Необовʼязковий Тип: String | URL сторінки товару |
brand | Apple Необовʼязковий Тип: String | Назва бренду |
tag_discount | 10 Необовʼязковий, має бути відносною цифрою (%) | Відсоток знижки |
price_currency_code | UAH Необовʼязковий Тип: String | Код валюти ціни |
tag_oldprice | 224.38 Необовʼязковий Тип: Int | Стара ціна |
Якщо на товар діє знижка, інформація про нього може передаватися в такий спосіб:
{ "product_id": "1111", "unit_price": "270", "isInStock": 1, "price_currency_code": "UAH", "tag_oldprice": [ "300" ], "tag_discount": [ "10" ] }
JSON
А якщо на товар немає знижки, то:
{ "product_id": "1111", "unit_price": "270", "isInStock": 1, "price_currency_code": "UAH" }
JSON