Документация 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 — опциональная зависимость каждого пакета фреймворка (react-intlayer, next-intlayer, vue-intlayer, …), поэтому в большинстве проектов он уже установлен. Установите его явно, если ваша конфигурация пропускает опциональные зависимости (npm install --no-optional, …):

npm install @intlayer/analytics

Чтобы включить аналитику, достаточно установить пакет: значение analytics.enabled по умолчанию равно true, а @intlayer/config приводит его к false, если пакет не найден в вашем проекте. Если вы её не установите, все точки интеграции будут разрешаться в пустые операции (no-op) — см. Нулевые затраты, если не установлено ниже.

Настройка

Аналитике не нужна настройка, чтобы начать работу: она включена по умолчанию и переиспользует существующий блок конфигурации editor для эндпоинта и ключа проекта.

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.

Как отключить

Необязательный блок analytics настраивает — или полностью отключает — сбор данных:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  analytics: {
    enabled: false, // По умолчанию: true — исключает всю интеграцию из сборки
    flushInterval: 20_000, // Миллисекунды между двумя пакетными отправками
    sampleRate: 1, // Доля записываемых сессий, от 0 (ни одной) до 1 (все)
  },
};

export default config;

Удаление @intlayer/analytics даёт тот же эффект, что и enabled: false. Полный список полей см. в справочнике по конфигурации.

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

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

Никаких изменений в коде не требуется. Как только установлен @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(), чтобы связать цель с вариантом, который видела сессия:

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

</Tab> </Tabs>

Weights необязательны — передайте один на вариант, чтобы изменить распределение, например useExperiment("homepage-hero", ["default", "black_friday"], [9, 1]).

Затем дочерний компонент читает Variant словаря, который совпадает:

import { useIntlayer } from "react-intlayer";

export const HeroBanner = ({ variant }: { variant: string }) => {
  const { headline, cta } = useIntlayer("hero-banner", { variant });

  return (
    <section>
      <h1>{headline}</h1>
      <a>{cta}</a>
    </section>
  );
};

Чтение варианта в дочернем компоненте — это то, что делает это работающим вне React: в Vue, Svelte, Solid и Angular селектор, передаваемый в useIntlayer, захватывается при инициализации компонента, поэтому чтение должно происходить в компоненте, который монтируется только после того, как вариант известен.

Если эксперимент охватывает целую страницу, а не отдельный словарь, поместите вариант на provider вместо этого — см. Ambient variant. Каждый useIntlayer ниже затем разрешается против него без изменения места вызова.

Если вам нужно получить необработанное значение переменной за пределами компонента, обратитесь непосредственно к клиенту:

getVariant только присваивает — он не записывает экспозицию. Предпочитайте useExperiment(), иначе коэффициент конверсии не будет иметь знаменателя.

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

• Анонимность по дизайну: сессии идентифицируются по ротируемому 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), автоматически устанавливаемая @intlayer/config в 'false', когда пакет не установлен, analytics.enabled равно false или не настроен 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);

Только на стороне сервера. createIntlayerCMS() аутентифицируется с помощью clientId + clientSecret, и секрет никогда не доступен в браузере — этот фрагмент кода выполнял бы неаутентифицированные запросы, если бы он там работал. Держите его в обработчике маршрута, серверном действии или скрипте.

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

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