Первые шаги

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

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object	Общая информация
eventName	“ProductPage” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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 из javascript document.cookie, нужная нам cookie имеет имя “sc”
datetime	1579622183208	Timestamp (millisecond)
ProductPage	Обязательный Тип: 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,
    "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
COPY
MORE

Параметры

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

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object String	Общая информация
eventName	“AddToWishlist” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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	Идентификатор товара Должен совпадать с productKey на странице ProductPage
price	“201.95” Обязательный Тип: String	Цена за единицу товара
tag_[something]	["abc","bca"] Необязательный Тип: Array of Strings	Все дополнительные поля могут передаваться в этом параметре, обязательная приставка tag_ после которой можно написать любое название Таких параметров может быть несколько Значение этого параметра передается в виде массива данных, который можно записывать через запятую
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
COPY
MORE

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object String	Общая информация
eventName	“StatusCart” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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 из 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	Количество товаров
Tags	Необязательный Type: 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
COPY
MORE

Параметры

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

Параметры

Название	Пример	Описание
GeneralInfo	Обязательный Тип: Object	Общая информация
eventName	“ProductPage” Обязательный Тип: String	Название отправляемого события
siteId	“8A412DC” Обязательный Тип: String	Идентификатор вашего магазина, можно получить в поддержке eSputnik Статический параметр
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 eSputnik
user_name	"Gregori Boczynski" Необязательный Тип: String	Имя и Фамилия пользователя
cookies	"CDA68358-94FB-4D83-9655-3FEB3C4114A3" Обязательный Тип: Object String	Cookie sc – это 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
COPY

Параметры

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

Параметры

Название	Пример	Описание
search	"Coffe" Обязательный Тип: String	Вводимое значение со строки поиска. То, что мы ищем на сайте
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
COPY
MORE

Параметры

Название	Пример	Описание
ProductUpdate	Тип: Object Обязательный	Массив обновленных товаров и их параметров
siteId	site_id Обязательный Тип: String	Название сайта
product_id	430738 Обязательный Тип: Int	Идентификатор товара
isInStock	1 Обязательный, может быть 0 или 1 Тип: Int	Отвечает за наличие товара Параметр может принимать два значения: “0” - товар не в наличии “1” - товар в наличии Если наличие товара на сайте изменилось, а в фиде еще нет, то в базу запишется значение с сайта
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
COPY

А если на товар нет скидки, то:

{
 "product_id": "1111",
 "unit_price": "270",
 "isInStock": 1,
 "price_currency_code": "UAH"
}JSON
COPY

Первые шаги

Пользовательские данные

Email

Омниканальность

Автоматизация

Персонализация

Аналитика

Мультиязычность

Отслеживание событий и поведения

Товарные рекомендации

API

Смена системы

Документы

Интеграция

Передача данных о поведении посетителей сайта через REST API

ProductPage

Описание

Пример

Параметры

StatusCart

Описание

Пример

Параметры

Wishlist

Описание

Пример

Параметры

PurchasedItems

Описание

Пример

Параметры

ProductImpressions

Описание

Пример

Параметры

CategoryPage

Описание

Пример

Параметры

CustomerData

Описание

Пример

Параметры

SearchRequest

Описание

Пример

Параметры

ProductUpdate

Описание

Пример

Параметры