Как подключить счётчик полевых метрик (field/RUM)

This page has no English translation yet — the Russian original is shown.

Как подключить счётчик полевых метрик (field/RUM)

Задача документа. Дать однозначный ответ: откуда взять код для встраивания счётчика полевых метрик на сайте и как подключить его корректно (код, CSP, SPA, приватность, проверка установки).

Скрипт раздаётся из seo-tools по URL, а на сайт встраивается типовой блок — по принципу счётчиков Яндекс.Метрики / Google Analytics. Файл скрипта не копируется и не хостится самостоятельно.

Дополнительно: metrics.md (что измеряется), troubleshooting.md (диагностика), faq.md.

1. Адрес скрипта

Адрес	Свойства	Когда использовать
`https://seo-tools.velizarov.ru/rum/v0.3.1/rum.js`	версия в адресе, долгий кэш (immutable)	рекомендуется: обновление выходит по новому адресу, уже работающие встраивания не ломаются
`https://seo-tools.velizarov.ru/rum.js`	короткий адрес «последняя версия», короткий кэш	если не хотите фиксировать версию; учитывайте кэш браузера

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

2. Как получить код встраивания

Код встраивания = типовой блок (см. §3) со ссылкой на адрес seo-tools и вашим токеном проекта. Скопируйте блок и подставьте свой токен.

Способ	Статус	Как
Скопировать типовой блок из этого документа и подставить свой токен	Доступно	см. §3
Взять готовый блок со страницы проекта (кнопка «Скопировать»)	в разработке	на странице аналитики проекта появится готовый к копированию блок с уже подставленным токеном
Скопировать файл скрипта и раздавать его со своего сайта	запрещено	раздача — только из seo-tools; типовой блок — единственный способ встраивания

3. Готовый типовой блок

3.1. Вариант A — атрибуты `data-*` на теге скрипта (рекомендуется)

<!-- RUM counter (field metrics) -->
<script
  src="https://seo-tools.velizarov.ru/rum/v0.3.1/rum.js"
  data-token="rum_0123456789abcdef0123456789abcdef"
  data-endpoint="https://seo-tools.velizarov.ru/v1/rum"
  data-metrics="v2"
  data-sample="1.0"
  defer></script>

data-token — публичный токен вашего проекта. Это не секрет: он виден в HTML страницы, так и задумано. Токен даёт право только записывать события в ваш проект, но не читать данные.
data-endpoint — обязательно абсолютный адрес (https://seo-tools.velizarov.ru/v1/rum). По умолчанию скрипт использует относительный путь /v1/rum: на стороннем сайте он укажет на ваш домен, и события уйдут в никуда. Всегда задавайте абсолютный адрес.
data-metrics — v2 (расширенный набор, по умолчанию) или v1 (базовый набор: CWV и ошибки).
data-sample — доля собираемых сессий, 0...1 (по умолчанию 1.0).
defer — не блокирует разбор страницы.

3.2. Вариант B — `window.RUM_CONFIG` (задаётся до загрузки скрипта)

<script>
  window.RUM_CONFIG = {
    token: 'rum_0123456789abcdef0123456789abcdef',
    endpoint: 'https://seo-tools.velizarov.ru/v1/rum',
    metrics: 'v2',
    sampleRate: 1.0,
    debug: false
  };
</script>
<script src="https://seo-tools.velizarov.ru/rum/v0.3.1/rum.js" defer></script>

Приоритет по каждому полю: window.RUM_CONFIG → data-* на теге → значения по умолчанию (endpoint = "/v1/rum", sampleRate = 1.0, metrics = "v2", debug = false).

Нюанс CSP. Вариант B требует инлайнового <script>. На сайтах со строгой Content-Security-Policy без 'unsafe-inline' для инлайна нужен nonce/hash. Если политика строгая — используйте вариант A (data-*), он не требует инлайна.

Если token не задан, скрипт ничего не собирает и не отправляет (странице не мешает).

4. Требования к Content-Security-Policy сайта

Скрипт загружается с домена seo-tools, а события отправляются через navigator.sendBeacon/fetch (оба попадают под connect-src):

Content-Security-Policy:
  script-src  'self' https://seo-tools.velizarov.ru;
  connect-src 'self' https://seo-tools.velizarov.ru;

script-src — чтобы загрузить скрипт с seo-tools.
connect-src — чтобы отправить события (sendBeacon/fetch).
При варианте B дополнительно нужен инлайновый скрипт (nonce/hash) либо переход на вариант A.
Отправка выполняется «простым» запросом (Content-Type: text/plain;charset=UTF-8), поэтому предварительный CORS-запрос (preflight) не выполняется; сервис отвечает 200 {"ok":true} (приём «прощающий» — открытая страница не ломается).

5. SPA и клиентские переходы

Скрипт сам обрабатывает клиентскую навигацию: перехватывает history.pushState/replaceState, слушает popstate/hashchange, а также pagehide/visibilitychange/beforeunload и возврат из bfcache (pageshow.persisted). Дополнительный код на SPA не требуется.

Что важно знать:

Реальный переход (смена pathname) отправляет события уходящей страницы и начинает сбор заново для новой. Такой просмотр помечается как «переход в SPA».
«Технический» переход (меняются только query/hash) не создаёт новый просмотр — метрики продолжают относиться к той же странице (двойных просмотров нет).
На переходах внутри SPA не собираются TTFB_*, FCP, FID — для них нет данных навигации. Это ожидаемое поведение, а не ошибка.

6. Заголовок `Timing-Allow-Origin` (полнота метрик по ресурсам)

Объём ответов (RES_BYTES) считается по данным о ресурсах только для ресурсов своего домена и для сторонних ресурсов, которые отдали заголовок Timing-Allow-Origin.
Для сторонних ресурсов без этого заголовка размер не передаётся браузером (transferSize = 0). Такие ресурсы не «исчезают»: их количество учитывается счётчиком RES_XORIGIN, чтобы не создавать иллюзию полного объёма.
Чтобы видеть байты сторонних ресурсов (CDN, шрифты, аналитика), добавьте на их ответы: Timing-Allow-Origin: https://ваш-сайт.ru (или *, если политика позволяет).

7. Приватность и согласие

Что уже сделано в скрипте (доступно):

Без cookie и без персональных данных: адрес страницы передаётся как origin + pathname (без query/hash); referrer и IP не отправляются; адреса ресурсов не отправляются (только агрегаты).
Эфемерный идентификатор сессии: генерируется случайно, хранится в пределах вкладки (перестаёт действовать после 30 минут бездействия), никогда не попадает в cookie и не сохраняется долговременно.
Сообщения об ошибках JS усечены до 200 символов; значение токена и содержимое отправляемых данных не журналируются.
Токен — публичный идентификатор записи, не секрет.

Что ещё не реализовано (планируется):

Учёт сигналов «не отслеживать» (DNT/GPC) и автоматическая связка с consent-баннером сайта — пока не встроены.

Рекомендация до появления такой связки. На сайтах, где согласие обязательно, подключайте счётчик после получения согласия — вставляя тег <script> с нужными data-* динамически.

8. Проверка установки (как убедиться, что данные идут)

Приём включён для проекта — да, в настройках проекта (иначе события отбрасываются).
Токен активен — да, в списке токенов проекта.
Отладка на странице: временно добавьте data-debug="true" → в консоли браузера появятся сообщения вида sent via sendBeacon N events.
Сеть: DevTools → Network → фильтр rum → должен быть POST /v1/rum → 200 с телом {"ok":true}. Запрос уходит при уходе/скрытии страницы или смене pathname (не мгновенно при загрузке).
Признак «данные доходят»: в личном кабинете у токена видно время последнего использования — если оно обновляется, события принимаются.
Аналитика: откройте страницу аналитики проекта. Данные появляются после агрегации за UTC-день (сегодняшний день может показываться как неполный).

Если шаги 1–5 проходят, а на странице аналитики данных нет — см. troubleshooting.md и учитывайте UTC и задержку агрегации.

9. Набор метрик и включение расширенного набора

Пакет событий проверяется целиком: если в пакете есть хотя бы одно неизвестное сервису имя метрики, весь пакет отбрасывается.
Поэтому набор метрик на сайте должен соответствовать набору, поддерживаемому сервисом:
- поддерживается расширенный набор → используйте metrics="v2";
- поддерживается только базовый набор → используйте metrics="v1".
Расширенный набор включается на стороне сервиса до того, как вы перейдёте на metrics="v2" на сайте.

10. См. также

metrics.md — что измеряет каждая метрика, единицы, пороги, ограничения.
troubleshooting.md — почему данных нет и что делать.
faq.md — короткие ответы на частые вопросы.