Клиентская аналитика

Verstka отправляет авторские события виджетов только через уже установленные на странице API GA4 и Яндекс Метрики. Viewer не загружает и не инициализирует провайдеры.

interface AnalyticsOptions {
  googleMeasurementId?: string
  yandexCounterId?: number
}

interface InitOptions {
  dev?: boolean
  debug?: boolean
  viewerUrl?: string
  analytics?: false | AnalyticsOptions
}

await initArticle(articleRoot, {
  analytics: {
    googleMeasurementId: 'G-XXXXXXXXXX',
    yandexCounterId: 12345678
  }
})

await initArticles(document, {
  analytics: {
    googleMeasurementId: 'G-XXXXXXXXXX',
    yandexCounterId: 12345678
  }
})

await initArticles(document, { analytics: false })

Приоритет и полное отключение

Для каждого провайдера отдельно используется валидный ID статьи, а при его отсутствии — валидный ID из InitOptions.analytics. Поэтому Google из статьи и Yandex из SDK работают одновременно. Пустое или невалидное значение статьи не блокирует валидный fallback SDK.

analytics: false отключает все вызовы, созданные Verstka, включая сохранённые настройки статьи и SDK fallback. Оно не отключает Enhanced Measurement, карту кликов, автоматические цели и другие наблюдения, принадлежащие установленному на сайте тегу.

При повторном вызове инициализации активного корня действуют первые options. Чтобы применить новые, вызовите destroy-функцию и инициализируйте тот же корень заново.

API провайдеров на стороне сайта

Для Google viewer вызывает только:

gtag('event', eventName, { send_to: measurementId })

Для Yandex сначала проверяется точный legacy-счётчик и вызывается yaCounter<ID>.reachGoal(eventName). Только если точного callable legacy API нет, вызывается ym(ID, 'reachGoal', eventName). После попытки legacy fallback на ym не выполняется, даже если legacy-вызов завершился ошибкой.

V1 не поддерживает Universal Analytics, прямые GTM custom-event objects, поиск провайдеров/счётчиков, загрузку скриптов, config/init, page views, пользовательские параметры, callbacks, retries или подтверждение доставки. Страница только с GTM должна намеренно предоставить совместимый gtag; установка второго Google-тега не является решением.

Согласие, приватность и доверие

Сайт отвечает за CMP, правовое основание, порядок consent и жизненный цикл тегов. Google consent defaults должны быть настроены до viewer: видимый Show может произойти сразу после гидратации. До согласия используйте analytics: false, затем destroy/reinitialize после согласия; подавленные Once-события не проигрываются задним числом.

ID назначения находятся в публичном JSON статьи. Только доверенные издатели могут выбирать их. Если авторы статьи не должны выбирать аналитику клиента, сайт обязан передать analytics: false в v1.

Verstka явно передаёт только имя события и ID назначения. Провайдер сайта может добавить page URL, referrer, title, device, cookie, consent, identity и session context. Не включайте персональные данные в имена. В SPA обновляйте provider-owned page context. Тег внутри iframe должен находиться в том же iframe; viewer не обращается к window.parent.

События и режим Once

Show — переход от отсутствия положительного пересечения viewport к положительному после гидратации. Hover — mouseenter корня виджета. Click — capture-listener на корне без preventDefault и остановки события.

Once хранится только в памяти страницы, по ключу root + widget + trigger + event name. Destroy/reinitialize того же корня не сбрасывает Once; новый DOM-корень или reload сбрасывает. Storage не используется. Если провайдер отсутствовал во время Once-попытки, replay после его появления нет. События с выключенным Once используют провайдера, появившегося к следующему повторению.

Цели и ограничения Яндекс Метрики

reachGoal не создаёт цель. Для конверсии заранее настройте совпадающую цель «JavaScript-событие» либо event-ID шага составной цели. Автоматические цели отдельны; их рекомендованные ID ym-* не совпадают с vrstk_*.

Метрика регистрирует одну и ту же цель одного счётчика не чаще одного раза в секунду, поддерживает до 200 ручных целей и до 400 зарегистрированных online conversions на тег за пользовательскую сессию Метрики. Обработанный reachGoal считается активностью визита и может продлить его. Поэтому повторный Hover может создать большой объём и исчерпать лимит зарегистрированных конверсий. Заблокированный, несовпавший или подавленный вызов не следует автоматически считать зарегистрированной конверсией.

Ошибки и отладка

Callable global и запись в очередь доказывают попытку вызова, но не получение или регистрацию провайдером. Обработке могут помешать consent, CSP, blocker или сеть. Ошибка аналитики не должна ломать статью.

Для GA4 проверяйте Tag Assistant и, только при доступе к property, DebugView. Для текущего кода Метрики используйте ?_ym_debug=2, для previous code — ?_ym_debug=1. Не заявляйте provider processing без доступа к нужному property/counter и коррелированных данных в Events/report.

Проверка через mock-clients

Mock host всегда передаёт Google G-2RQ4P9EBVF и Yandex 95333140 как SDK fallback. Обычный/off режим полностью offline. mockAnalytics=record использует заранее установленные doubles без скриптов. mockAnalytics=live разрешён только для committed fixture client-analytics; production viewer никогда не устанавливает теги.

Проверяйте /standard/client-analytics, /feed/client-analytics и /standard/client-analytics/no-js после:

yarn workspace viewer-core build
yarn workspace renderer build:critical-css
yarn workspace mock-clients test:browser

Live допускается только при явном разрешении на тестовую телеметрию, подтверждённых dedicated non-production destinations, выключенном GA Enhanced Measurement, выключенных Yandex Automatic goals/лишнем сборе, проверенных фильтрах и отсутствии персональных данных. Наличие вызова в console не доказывает зарегистрированную конверсию.