Передача данных о поведении посетителей сайта через 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

Код ответа 204. Авторизация не нужна.

ProductPage

Описание

Для качественного ранжирования товаров/категорий или для отправки триггеров по брошенным просмотрам необходимо отправить запрос, в котором будет указано:

какую карточку товара в данный момент просматривает пользователь,
цену и наличие товара.

Пример

{
  "GeneralInfo": {
    "eventName": "ProductPage",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object	Общая информация
eventName	“ProductPage” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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" Обязательный Type: Object String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”
datetime	1579622183208	Timestamp (millisecond)
ProductPage	Обязательный Type: Object	Описание события
productKey	“72354” Обязательный Тип: String	Идентификатор товара Должен совпадать с productKey на странице StatusCart и PurchasedItems
price	“754 USD” Необязательный Тип: String	Цена за единицу товара. Может передаваться с обозначением денежной валюты Если цена на сайте изменилась, а в фиде еще нет, то в базу запишется значение с сайта
isInStock	“1” Необязательный Тип: Int	Отвечает за наличие товара Параметр может принимать два значения: “0” - товар не в наличии “1” - товар в наличии Если наличие товара на сайте изменилось, а в фиде еще нет, то в базу запишется значение с сайта
tag_[something]	["abc","bca"] Необязательный Тип: Array of Strings	Все дополнительные поля могут передаваться в этом параметре, обязательная приставка tag_ после которой можно написать любое название Таких параметров может быть несколько Значение этого параметра передается в виде массива данных, который можно записывать через запятую
Tags	Необязательный Тип: Object	Дополнительные поля

StatusCart

Описание

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

Пример

{
  "GeneralInfo": {
    "eventName": "StatusCart",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object String	Общая информация
eventName	“StatusCart” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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 и PurchasedItems Должен быть идентичным GUID’у события PurchasedItems Может быть сгенерирован из случайных цифр и латинских букв
StatusCart	Обязательный Тип: Object String	Описание объектов события Является массивом объектов, который содержит товары добавленные в корзину
productKey	“430738” Обязательный Тип: String	Идентификатор товара Должен совпадать с productKey на странице ProductPage
price	“201.95” Обязательный Тип: String	Цена за единицу товара
discount	“180” Необязательный Тип: String	Скидочная цена за единицу товара
quantity	“1” Обязательный Type: Int	Количество товаров
price_currency_code	"UAH" Необязательный Тип: String	Обозначение денежной валюты
tag_[something]	["abc","bca"] Необязательный Тип: Array of Strings	Все дополнительные поля могут передаваться в этом параметре, обязательная приставка tag_ после которой можно написать любое название Таких параметров может быть несколько Значение этого параметра передается в виде массива данных, который можно записывать через запятую
Tags	Необязательный Тип: Object	Дополнительные поля

PurchasedItems

Описание

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

Пример

{
  "GeneralInfo": {
    "eventName": "PurchasedItems",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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": {
    "GUID": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
    "OrderNumber": "123/2017",
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object String	Общая информация
eventName	“StatusCart” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
user_phone	"1-541-754-3010" Необязательный Тип: String	Номер телефона в международном формате
user_email	"user@mail.com" Необязательный Тип: String	Email пользователя
user_es_contact_id	"255830499" Необязательный Тип: String	ID клиента в базе eSputnik
datetime	1579622183208	Timestamp (millisecond)
cookies	"CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обязательный Тип: Object String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”
GUID	“6F9619FF-8B86-D011-B42D-00CF4FC964FF” Обязательный Тип: String	Уникальный идентификатор, связывающий два события StatusCart и PurchasedItems Должен быть идентичным GUID’у события StatusCart Может быть сгенерирован из случайных цифр и латинских букв
OrderNumber	“123/2017” Обязательный Тип: String	Номер заказа Является подтверждением совершения покупки
Tags	Необязательный Тип: Object	Дополнительные поля

PurchasedItems (one click)

Описание

Событие используется в случае “покупки в 1 клик”, либо “покупки в кредит”. Событие отправляется опционально, в зависимости от способов покупки в интернет-магазине.

Пример

{
  "GeneralInfo": {
    "eventName": "PurchasedItems",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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": {
      "block_id": [
        "21246_r335v507"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object String	Общая информация
eventName	“StatusCart” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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 из javascript document.cookie, нужная нам cookie имеет имя “sc”
OrderNumber	“123/2017” Обязательный Тип: String	Номер заказа Является подтверждением совершения покупки
PurchasedItems	Тип: Array of Strings	Список товаров
product_id	“430738” Обязательный Тип: String	Идентификатор товара Должен совпадать с productKey на странице ProductPage
unit_price	“201.95” Обязательный Тип: String	Цена за единицу товара
quantity	“1” Обязательный Тип: Integer	Количество товаров
block_id	“21246_r335v507” Обязательный Тип: String	Идентификатор блока рекомендаций. Можно получить от поддержки eSputnik.
Tags	Необязательный Type: Object	Дополнительные поля

ProductImpressions

Описание

ProductImpressions - событие, отправка которого позволяет отслеживать показы блоков. По умолчанию отправляется скриптом, по JS API. Дополнительно передавать не нужно.

Пример

{
  "GeneralInfo": {
    "eventName": "ProductImpressions",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Array of Objects	Общая информация
eventName	“ProductImpressions” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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" Обязательный Type: Оbject String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”
ProductImpression	Обязательный Тип: Array of Objects	Описание объектов события Является массивом объектов
product_id	“430968” Обязательный Тип: String	Идентификатор товара или категории, который есть в feed’е
container_type	“1253” Обязательный Тип: String	Номер блока рекомендаций.
Tags	Необязательный Type: Object	Дополнительные поля

CategoryPage

Описание

Возможно использование

для триггеров,
просмотра сайта с посещением категории, без посещения карточки товаров,
просмотра сайта без любого посещения категории/товара.

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

Пример

{
  "GeneralInfo": {
    "eventName": "CategoryPage",
    "siteId": "8A412DC",
    "datetime":1579622183208,
    "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": "Для малышей"
    },
    "Tags": {
      "some_tags": [
        "1",
        "a2"
      ],
      "some_tags1": [
        "4",
        "gg"
      ]
    }
  }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Type: Object	Общая информация
eventName	“ProductPage” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
user_phone	"1-541-754-3010" Необязательный Тип: String	Номер телефона в международном формате
user_email	"user@mail.com" Необязательный Тип: String	Email пользователя
user_es_contact_id	"255830499" Необязательный Тип: String	ID клиента в базе eSputnik eSputnik
user_name	"Gregori Boczynski" Необязательный Тип: String	Имя и Фамилия пользователя
cookies	"CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обязательный Type: Object String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”
datetime	1579622183208	Timestamp (millisecond)
CategoryPage	Обязательный Type: Object	Описание события
categoryKey	“Для малышей” Обязательный Тип: String	Название или ID категории.
Tags	Необязательный Type: Object	Дополнительные поля

CustomerData

Описание

Для отправки триггеров по брошенным корзинам и брошенным просмотрам необходимо отправить запрос, в котором будет указана информация о пользователе.

Email должен отправляться минимум, в личном кабинете, на странице “Спасибо за заказ” и при регистрации.

Пример

{
 "GeneralInfo": {
   "eventName": "CustomerData",
   "siteId": "8D3869C",
   "datetime":1579622183208,
   "user_phone": "3801111111111",
   "user_email": "user@mail.com",
   "user_es_contact_id": "255830499",
   "user_name": "Johny",
   "cookies": {
     "sc": "CDA68358-94FB-4D83-9655-3FEB3CGGG1"
   }
 }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Array of Objects	Общая информация
eventName	“StatusCart” Обязательный Тип: String	Название отправляемого события
siteId	“8D3869C” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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" Обязательный Type: Object String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”

CustomEvent

Описание

CustomEvent не входит в список стандартных событий. Вы можете дать каждому из них уникальное имя, отражающее выполняемое действие. Специально настроенные события можно использовать для построения пользовательских аудиторий.

Пример

{
    "GeneralInfo": {
        "eventName": "CustomEvent",
        "datetime":1579622183208,
        "screendim": {
            "h": 1200,
            "w": 2304
        },
        "adblockEnabled": true,
        "device": "Desktop",
        "browser": {
            "name": "Chrome",
            "chrome": true,
            "version": "74.0",
            "webkit": true,
            "a": true
        },
        "siteId": "8A412DC",
        "cookies": {
            "sc": "CDA68358-94FB-4D83-9655-3FEB3C4114A3"
        },
        "s_location": "https://example.com/product_id.html",
        "referrer": "https://example.com",
        "user_client_id": "",
        "user_city": "",
        "user_card_id": "",
        "user_name": "Gregori Boczynski",
        "user_phone": "1-541-754-3010",
        "user_email": "user@mail.com",
        "user_es_contact_id": "255830499"
    },
    "CustomEvent": {
     "EventName":"my_event",
     "Tags": {
     "some_tags": [
         "1",
         "a2"
     ],
     "some_tags1": [
       "4",
     "gg"
     ]
}
    }
}

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Array of Objects	Общая информация
eventName	“CustomEvent” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
user_phone	"1-541-754-3010" Необязательный Тип: String	Номер телефона в международном формате
user_email	"user@mail.com" Необязательный Тип: String	Email пользователя
user_name	"Gregori Boczynski" Необязательный Тип: String	Имя/Фамилия пользователя
datetime	1579622183208	Timestamp (millisecond)
cookies	"CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обязательный Type: Object String	Cookie sc - является cookie сгенерированной нашим скриптом, которую можно взять с сайта Пример вызова данной cookie из javascript document.cookie, нужная нам cookie имеет имя “sc”
CustomEvent	Обязательный Тип: Array of Objects	Описание пользовательского события
EventName	"my_event" Обязательный Тип: String	Название пользовательского события
Tags	Необязательный Тип: Array of Objects	Пользовательские поля, где "some_tags" - название поля, а "1", "a2" - его значение(я) (всегда имеют тип список строк)

ProductUpdate

Описание

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

Пример

{
  "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",
      "unit_price": "201.95",
      "isInStock": "1",
      "tag_discount": ["10"],
      "tag_oldprice": ["224.38"],
      "price_currency_code": "UAH",
      "category": "level3",
      "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"
      ]
    }
  ]
}

Параметры

Название	Пример	Описание
ProductUpdate	required	required
siteId	site_id	required
product_id	430738	required
isInStock	1	required, could be 0 or 1
unit_price	201.95	optional field
description	Some description	optional field
name	iPhone 7	optional field
imgurl	https://domain.com/apple/product_large.png	optional field
brand	Apple	optional field
tag_discount	10	optional field
price_currency_code	UAH	optional field
tag_oldprice	224.38	optional field

Если на товар действует скидка, информация о нем должна передаваться следующим образом:

{
 "product_id": "1111",
 "unit_price": 270,
 "isInStock": 1,
 "price_currency_code": "UAH",
 "tag_oldprice": [
   "300"
 ],
 "tag_discount": [
   "10"
 ]
}