Установка и настройка Web-SDK

Web-SDK автоматически собирает поведение посетителей на сайте: просмотры страниц, клики, взаимодействие с формами и полями, активность, прокрутку, переключение вкладок и, по желанию, запись сессии (rrweb). Данные уходят на ваш сервер Rockstat через sendBeacon или fetch.

События объединяются в сессии прямо в браузере и классифицируются по источнику: реклама, органика, соцсети, партнёрские переходы, реферальные, внутренние и прямые. Подробнее о сессиях. К автоматическим событиям можно добавлять свои с любым набором параметров. Работает на десктопе и в мобильных браузерах.

Вставка кода

Сниппет ставится на все страницы сайта, как можно выше в <head>. Сайтов может быть несколько, каждый отличается по projectId. Актуальная версия сниппета лежит в репозитории web-sdk.

<script>
  !function (w, d, st, cn, hs, lj, rst, se, he) {
    if(w.rstat4) return; rst = w.rstat4 = function () {
      var a = Array.prototype.slice.call(arguments);
      a.length && a[0] === cn && rst._a(Object(a[1]));
      return rst.doCall ? rst.doCall.call(rst, a) : rst._q.push(a) && 0; };
    rst.push = rst; rst._sv = '5.2.1'; rst._q = [];
    rst._jsl = function (src) {
      se = d.createElement(st); se.async = !0; se.src = src;
      he = d.getElementsByTagName(st)[0]; he.parentNode.insertBefore(se, he); };
    rst._a = function(conf){
      rst._host = conf.server; rst._prefix = conf.pathPrefix || '';
      rst._host && rst._jsl(hs+rst._host+rst._prefix+lj); }
  }(window, document, 'script', 'configure', 'https://', '/lib.js');
  // --- configuration ---
  rstat4('configure', {
    server: 'YOUR_SUBDOMAIN.DOMAIN' // <<< replace
  });
  rstat4('page'); // <<< remove if needed
</script>

Сниппет создаёт глобальную функцию rstat4, ставит в очередь все вызовы до загрузки библиотеки, а при вызове configure с параметром server подключает https://<server>/lib.js. После загрузки библиотека инициализируется на DOMContentLoaded и выполняет накопленную очередь. Весь API — одна функция: первый аргумент — имя метода, остальные — его параметры.

Библиотека работает только на https. Для локальной разработки на http добавьте в конфигурацию allowHTTP: true.

Минимальная конфигурация

Обязателен только server. Остальное имеет разумные значения по умолчанию: клики по ссылкам, формы, активность и прокрутка включены, запись сессии выключена.

rstat4('configure', {
  server: 'stat.example.com',
  projectId: 1,                        // необязательно, иначе считается из домена
  trackClicks: { allClicks: true },    // клики по любым элементам, не только по ссылкам
  trackForms: { encryptionKey: '...' } // шифровать значения полей форм в браузере
});
rstat4('page');

Полный список параметров и настройки каждого трекера описаны в разделе Сниппет и конфигурация.

Параметр	Тип данных	Значение по умолчанию	Описание
server	String	null	Обязательный. Домен сервера трекера без схемы и пути. Пример: stat.example.com. С него загружается lib.js, на него уходят события
pathPrefix	String	''	Префикс пути на сервере. lib.js и события запрашиваются по адресам вида <pathPrefix>/lib.js, <pathPrefix>/band/t4k.json
urlMark	String	'band'	Сегмент пути для доставки событий: /<urlMark>/t4k.json
projectId	Number	хеш домена	Идентификатор проекта. Если не указан, вычисляется из домена страницы, см. buildProjectId
allowHTTP	Boolean	false	Разрешить работу на страницах по http. По умолчанию SDK работает только на https
allowSendBeacon	Boolean	true	Отправлять события через navigator.sendBeacon
allowXHR	Boolean	true	Разрешить отправку через fetch
sessionTimeout	Number	1800	Тайм-аут сессии в секундах: сколько времени без событий должно пройти, чтобы началась новая
lastCampaignExpires	Number	7776000	Срок хранения последней рекламной кампании в секундах (90 дней)
initialUid	Number	0	Начальный uid посетителя, если он должен быть задан снаружи
cookieDomain	String	домен страницы	Домен, на который ставятся cookie
cookiePath	String	'/'	Путь cookie
cookiePrefix	String	'rst4-'	Префикс имён всех cookie, которые ставит SDK
lcPrefix	String	'rst4:'	Префикс ключей в localStorage
trackActivity	Boolean, Object	{ zeroEvents: false, scrollEvents: true, domEvents: true }	Активность и прокрутка: события activity и scroll. Настройки в разделе «Трекеры»
trackClicks	Boolean, Object	{ allClicks: false }	Клики: link_click и, при allClicks, element_click
trackForms	Boolean, Object	{}	Формы и поля: form_submit, field_focus, field_blur, field_change, field_invalid
trackPages	Boolean	false	Зарезервировано. Автоматическое отслеживание смены URL в SPA пока не реализовано, вызывайте page вручную
trackRecord	Boolean, Object	{ autostart: false }	Запись сессии (rrweb)
browserEvents	Boolean, Object	{ unloadHandlers: true, visibilityHandlers: true }	События page_unload и page_visibility
activateWs, wsServer, wsPath	Boolean, String, String	false, null, '/wss'	Транспорт WebSocket. Зарезервировано, в текущей версии не используется
pixelSync	Boolean, Object	false	Перехват пикселей. Зарезервировано, в текущей версии не используется

Просмотры страниц и SPA

Событие page библиотека сама не отправляет: вызывайте rstat4('page') после configure, а в одностраничных приложениях — при каждой смене маршрута. В page можно передать данные о странице: тип, категорию, идентификатор товара.

// React Router, Vue Router и т.п.: на каждую смену маршрута
router.afterEach(() => {
  rstat4('page', { type: 'category', name: 'Товары для дома' });
});

Проверка установки

Включите подробный лог в консоли и подпишитесь на исходящие сообщения:

rstat4('enableLogger');
rstat4('onMessage', function (msg) {
  console.log('rockstat →', msg.name, msg);
});

В консоли появятся строки RST/Tracker: Initializing..., затем события session, page, page_loaded. Во вкладке Network должны быть POST-запросы на https://<server>/band/t4k.json с ответом 200. Лог можно включить и до загрузки библиотеки: window._rst4_logger = true.

Идентификатор посетителя доступен после инициализации:

rstat4('onReady', function () {
  console.log('uid:', rstat4('getUid'));
});

Установка через GTM

Загрузчик можно ставить через Google Tag Manager, но рекомендуется вставлять его прямо в код сайта:

Он загрузится первым и успеет перехватить синхронизации идентификаторов с другими сервисами.
Будет учтено больше «отказников», которые уходят до загрузки GTM.
Платформа работает на вашем домене, и блокировщики рекламы её не режут, в отличие от GTM.

События из Data Layer

В GTM создайте тег «Пользовательский HTML»:

<script>
  var name = ({{category}} || '') + '-' + ({{action}} || '');
  var data = {};
  if ({{category}}) data.category = {{category}};
  if ({{action}}) data.action = {{action}};
  if ({{label}}) data.label = {{label}};
  if ({{value}}) data.value = {{value}};
  rstat4('event', name, data);
</script>

Вместо category, action, label, value подставьте ваши пользовательские переменные.

Формирование projectId

projectId указывать необязательно: без него он вычисляется из домена страницы.

отрезаются поддомены www и m;
если в домене осталось три и более уровней (aaa.bbb.ru), снимается один уровень (bbb.ru);
из полученного домена считается числовой хеш.

Посмотреть результат для любого домена можно в консоли:

rstat4('buildProjectId', 'www.shop.example.com')
// → ['example.com', 1617632140]

Если у вас несколько сайтов на поддоменах одного домена и их данные нужно разделять, задавайте projectId явно: автоматический расчёт для них совпадёт.

Что дальше

Сниппет и конфигурация — все параметры и настройки трекеров.
JavaScript API — свои события, идентификация, коллбеки, запись сессии.
Автоматические события — что собирается без вашего участия.
Структура событий — формат сообщений на сервере.