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

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

Зміст

Що відстежується

@intlayer/analytics об'єднує в пакети (batch) три типи анонімних подій:

Події збираються в пам'яті та надсилаються як один пакетний запит приблизно кожні 20 секунд — а не при кожному натисканні клавіші або рендерингу — тому аналітика ніколи не впливає на час першого рендерингу і не додає запити на кожну взаємодію.

Як це працює для A/B-тестування контенту

Intlayer вже дозволяє вам оголошувати Варіанти (Variants) контенту (наприклад, словник hero-banner з варіантами control та black_friday). @intlayer/analytics замикає цикл:

1. getVariant(experimentKey, variants) детерміновано призначає кожну анонімну сесію варіанту — це чиста функція від ID сесії та ключа експерименту, тому призначення є стабільним протягом усієї сесії і не вимагає запитів до сервера (server round-trips) до першого рендерингу (без мерехтіння і зсувів макета).
2. Кожна подія content_exposure містить показаний variant.
3. useConversion() дозволяє пов'язати мету (наприклад, "cta_click") з цим варіантом.
4. Ендпоінт результатів експериментів у дашборді порівнює коефіцієнти конверсії (conversion rates) за варіантами, включаючи статистичну значущість (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 автоматично:

• ініціалізує клієнт аналітики при монтуванні (mount),
• записує page_view при початковому завантаженні,
• записує page_view при кожній зміні локалі,
• запускає цикл очищення (flush) з інтервалом ~20 с і надсилає всі події, що залишилися, при розмонтуванні / закритті вкладки (через navigator.sendBeacon, з відкатом (fallback) на fetch(..., { keepalive: true })).

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

Щоразу, коли useIntlayer розв'язує фрагмент контенту для відображення, інтерпретатор повідомляє про подію content_exposure для цього точного dictionaryKey + шляху до ключа + локалі — знову ж таки, жодних змін у коді не потрібно. Повторні покази одного й того ж вузла в межах вікна очищення (flush window) об'єднуються в одну подію з лічильником (count), тому список, що перемальовується (re-render) 50 разів, не надсилає 50 подій.

Відстеження конверсій для A/B-тестування

Використовуйте useConversion(), щоб пов'язати мету з варіантом, який бачила сесія:

Розв'язання варіанту на стороні клієнта

Конфіденційність та продуктивність

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

Нульові витрати, якщо не встановлено

@intlayer/analytics дотримується того ж патерну опціональних залежностей, що й @intlayer/editor:

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

Дашборд: Сторінка Analytics

Як тільки ваш проект збере події, сторінка Analytics у дашборді Intlayer (видна в бічній панелі після вибору проекту) покаже:

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

Довідник API бекенда (Backend API reference)

Всі ендпоінти для читання вимагають автентифікації; прийом даних публічний і асоціюється за 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 (Visual Editor)
• Довідник з конфігурації (Configuration Reference)
• Посібник із самостійного хостингу (Self-Hosting)