Вызовы счётчика — track, setTrackData, koLayer, ko_options — Справочный центр

Обновлено: 19 августа 2026 г.

Справочник по тому, что счётчик КО отдаёт в window. Как поставить обёртку и отправить первое событие — Свои события из одностраничного приложения и Свои события с обычного сайта; как назвать событие — Словарь событий.

Счётчик описан таким, какой он сегодня. Это не контракт с обещанием совместимости.

Два вызова

Всё, что нужно для своих событий, — два метода модуля ko.visit:

ko.visit.track(event_name, envelope)     // отправить событие
ko.visit.setTrackData(data, merge)       // задать контекст следующих событий

ko.visit появляется только после загрузки счётчика. До этого — очередь koLayer.

track(event_name, envelope)

event_name — строка, имя события. envelope — конверт, а не данные события:

ko.visit.track('report_exported', {
  data:   { rows: 42, format: 'xlsx' },   // поля события — только здесь
  income: 0,                              // деньги, необязательно
  cost:   0,                              // расход, необязательно
});

Поля конверта:

Поле	Тип	Что делает
`data`	объект	Поля события. Разрез в отчёте строится измерением `field:data.<ключ>`
`income`	число	Складывается как деньги. Лежит рядом с `data`, не внутри
`cost`	число	То же, но расход
`entity`	строка	По умолчанию `visitor` — вторая часть формулы метрики. Менять незачем

Частая ошибка — плоский объект:

ko.visit.track('report_exported', { rows: 42 });   // ← rows уйдёт в служебную часть

Событие запишется, но rows не будет в его данных: разрез по этому полю даст одну пустую строку.

Сумма в data деньгами не станет — она сложится как обычное число. Деньги — только income и cost конверта.

setTrackData(data, merge)

Подмешивает поля в каждое следующее событие этой страницы.

ko.visit.setTrackData({ user_id: 42, plan: 'pro' }, true);   // дополнить
ko.visit.setTrackData({ user_id: 42 });                      // заменить весь контекст

merge по умолчанию false. Вызов без второго аргумента заменяет контекст целиком, а не дополняет его — второй setTrackData сотрёт то, что поставил первый. Если вы ставите контекст слоями по мере того, как факты становятся известны, второй аргумент обязателен.

При совпадении ключа побеждает контекст, а не событие. Поля контекста накладываются поверх data события, поэтому plan из контекста перезапишет plan, переданный в track. Один ключ живёт либо в контексте, либо в событии.

Контекст живёт в памяти страницы. Перезагрузка его обнуляет.

Очередь koLayer

Счётчик грузится асинхронно, и первое событие часто случается раньше него. До загрузки вызовы копятся в window.koLayer.

window.koLayer = window.koLayer || [];
window.koLayer.push(['visit', 'track', ['report_exported', { data: { rows: 42 } }]]);

Элемент очереди — один массив из трёх частей: имя модуля, имя метода, массив аргументов. Четыре отдельных аргумента в push счётчик не выполнит.

Функция тоже принимается и вызывается в контексте счётчика:

window.koLayer.push(function () { /* счётчик уже здесь */ });

При инициализации счётчик подменяет push собственной реализацией, поэтому после загрузки запись в очередь выполняется сразу, а не ждёт разбора. Отдельная ветка «счётчик уже загружен → зову напрямую» в обёртке всё равно полезна: она даёт возврат результата.

Внутри счётчика есть вторая очередь, о которой ничего делать не надо: событие, выпущенное до того, как визит получил идентификатор, ждёт в ней и уходит, когда визит открылся.

Опции счётчика — ko_options

Объект ko_options объявляется до загрузки счётчика; после — не читается.

var ko_options = {
  modules: {
    visit: {
      url_tracking_hash_router: false,
      url_tracking_query_patterns: ['*', '!utm_*', '!_*'],
      url_tracking_debounce_ms: 100,
    },
  },
};

Опция	По умолчанию	Что делает
`url_tracking_hash_router`	`false`	`true`, если маршруты приложения идут через `#/`
`url_tracking_query_patterns`	`['', '!utm_', '!_*']`	Какие query-параметры участвуют в адресе страницы. `*` — разрешить всё, `!` — исключить по маске
`url_tracking_debounce_ms`	`100`	Пауза перед обработкой смены адреса

Фильтр параметров — то, чем страница не размножается в отчёте на десяток строк из-за ?tab=2&_r=17. По умолчанию utm_* и всё, начинающееся с _, уже исключены.

Отладка

Что	Как
Включить отладку	`?ko_debug` в адресе страницы
Заглушить счётчик	`?ko_off` в адресе страницы
Проверить, что событие ушло	Вкладка Network, запрос `visit.php?type=event`; тело запроса — конверт целиком

Счётчик молчит и без ключа: если в установочном коде пустой hash, счётчик выключается сам.

Ограничения

Дедупликации нет. Один вызов — одна запись. Экран, который перерисовывается сам, даст событие на каждый проход; ключ «это уже посчитано» — на вашей стороне.
Событие живёт на визите. У действия, случившегося не в браузере — оплата, подтверждённая на сервере, ночной пересчёт, — визита нет, и событием сайта оно быть не может.
Контекст не переживает перезагрузку: он в памяти страницы.
Событие на уходе со страницы может не успеть, если счётчик ещё не загрузился. Надёжный якорь — факт на принимающем экране.
Просмотры страниц счётчик пишет сам, включая маршруты SPA. Своя подписка на роутер удваивает просмотры.

Что рядом

Словарь событий — как называть события и где ставить вызов
Свои события из одностраничного приложения
Подключение сайта — установка счётчика