Документация Intlayer Analytics

@intlayer/analytics — это дополнительный пакет, который показывает, какой контент на самом деле видят ваши посетители (какая страница, в какой локали и какой именно фрагмент переведенного контента), чтобы вы могли лучше понимать свою аудиторию и проводить A/B-тестирование контента.

Содержание

Что отслеживается

@intlayer/analytics объединяет в пакеты три типа анонимных событий:

События собираются в памяти и отправляются как один пакетный запрос примерно каждые 20 секунд — а не при каждом нажатии клавиши или рендеринге — поэтому аналитика никогда не влияет на время первого рендеринга и не добавляет запросы на каждое взаимодействие.

Как это работает для A/B-тестирования контента

Intlayer уже позволяет вам объявлять Варианты контента (например, словарь hero-banner с вариантами control и black_friday). @intlayer/analytics замыкает цикл:

1. getVariant(experimentKey, variants) детерминированно назначает каждую анонимную сессию варианту — это чистая функция от ID сессии и ключа эксперимента, поэтому назначение стабильно на протяжении всей сессии и не требует серверных запросов до первого рендеринга (без мерцания и сдвигов макета).
2. Каждое событие content_exposure содержит показанный variant.
3. useConversion() позволяет связать цель (например, "cta_click") с этим вариантом.
4. Эндпоинт результатов экспериментов в дашборде сравнивает коэффициенты конверсии по вариантам, включая статистическую значимость (z-тест).

Установка

@intlayer/analytics — это одноранговая (peer), опциональная зависимость. Фреймворки не устанавливают её автоматически. Добавьте её вместе с intlayer:

npm install @intlayer/analytics

Если вы её не установите, все точки интеграции будут разрешаться в пустые операции (no-op) — см. Нулевые затраты, если не установлено ниже.

Настройка

Аналитика повторно использует существующий блок конфигурации editor — вам не нужно заполнять отдельную схему конфигурации для analytics:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Также используется как конечная точка для сбора аналитики
    clientId: "your-client-id", // Также используется как ключ проекта аналитики
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — базовый URL, на который отправляются события аналитики (POST {backendURL}/api/analytics/events).
• editor.clientId — открытый ключ проекта, присваиваемый каждому принятому событию. Он также действует как переключатель включения: аналитика остается полностью отключенной (и удаляется при tree-shaking, см. ниже), пока не настроен clientId.

Если вы самостоятельно размещаете (self-host) Intlayer, аналитика автоматически указывает на ваш собственный экземпляр, поскольку она использует общий editor.backendURL.

Поддержка фреймворков

Аналитика встроена в общий IntlayerProvider из react-intlayer, поэтому она доступна уже сегодня везде, где используется этот провайдер:

Использование

Автоматическое отслеживание на уровне провайдера

Никаких изменений в коде не требуется. Как только установлен @intlayer/analytics и настроен editor.clientId, IntlayerProvider автоматически:

• инициализирует клиент аналитики при монтировании,
• записывает page_view при начальной загрузке,
• записывает page_view при каждой смене локали,
• запускает цикл очистки (flush) с интервалом около 20 с и отправляет оставшиеся события при размонтировании / закрытии вкладки (через navigator.sendBeacon, с откатом на fetch(..., { keepalive: true })).

Автоматическое отслеживание на уровне узла

Каждый раз, когда useIntlayer разрешает фрагмент контента для отображения, интерпретатор сообщает о событии content_exposure для этого точного dictionaryKey + пути к ключу + локали — опять же, никаких изменений в коде не требуется. Повторяющиеся показы одного и того же узла в пределах окна очистки объединяются в одно событие со счетчиком (count), поэтому список, перерисовывающийся 50 раз, не отправляет 50 событий.

Отслеживание конверсий для A/B-тестирования

Используйте useConversion(), чтобы связать цель с вариантом, который видела сессия:

Разрешение варианта на стороне клиента

Конфиденциальность и производительность

• Анонимность по дизайну: сессии идентифицируются по ротируемому id; сервер когда-либо сохраняет только SHA-256 хэш этого id — никогда сам id и никогда IP-адрес.
• Приблизительное местоположение: только код страны, полученный из заголовков геолокации CDN (cf-ipcountry, x-vercel-ip-country, ...) — IP не считывается и не сохраняется.
• URL исключают параметры поиска по умолчанию, поэтому строки запроса никогда не фиксируются.
• Семплирование: sampleRate позволяет сохранять только часть событий показа контента в приложениях с высоким трафиком.
• Пакетная передача: один запрос примерно каждые 20 секунд (flushInterval) или раньше, если буфер заполнен (maxBufferSize) — никогда не отправляется один запрос на каждое событие.

Нулевые затраты, если не установлено

@intlayer/analytics следует тому же паттерну опциональных зависимостей, что и @intlayer/editor:

• каждая точка интеграции загружает пакет через динамический import(), обернутый в try/catch — приложение, которое никогда не устанавливает @intlayer/analytics, не увеличивает размер сборки (bundle) и не тратит ресурсы во время выполнения, а также никогда не видит ошибок;
• переменная окружения времени компиляции (INTLAYER_ANALYTICS_ENABLED), автоматически устанавливаемая в 'false' пакетом @intlayer/config, когда не настроен editor.clientId, позволяет бандлерам удалять весь код интеграции (dead-code-eliminate);
• аналитика отключена внутри iframe предварительного просмотра редактора/CMS Intlayer, поэтому сессии в редакторе никогда не учитываются как реальный трафик.

Дашборд: Страница Analytics

Как только ваш проект соберет события, страница Analytics в дашборде Intlayer (видна в боковой панели после выбора проекта) покажет:

• Активные пользователи — уникальные посетители за выбранное скользящее окно (7 / 30 / 90 дней).
• Пользователи сегодня и пользователи за последние 7 дней.
• Просмотры страниц за выбранное окно.
• График динамики уникальных посетителей по дням.
• Вкладки с разбивкой по Локалям и Местоположению, ранжирующие вашу аудиторию по локали и по стране.

Справочник API бэкенда

Все эндпоинты для чтения требуют аутентификации; прием данных публичный и ассоциируется по clientId в теле запроса.

Вы также можете вызывать их программно с помощью CMS SDK:

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

Полезные ссылки

• Динамические словари - Коллекции и варианты
• Intlayer CMS - CMS SDK
• Визуальный редактор Intlayer
• Справочник по конфигурации
• Руководство по самостоятельному хостингу (Self-Hosting)