diff --git a/docs/ENHANCED_LOGGING_GUIDE.md b/docs/ENHANCED_LOGGING_GUIDE.md new file mode 100644 index 0000000..8f777cd --- /dev/null +++ b/docs/ENHANCED_LOGGING_GUIDE.md @@ -0,0 +1,362 @@ +# 📊 Улучшенное логирование Google Analytics событий + +## ✨ Что изменилось + +Все события Google Analytics теперь логируются с **детальной информацией** в консоли браузера: + +### 1. **Page View события** (просмотры страниц) +### 2. **AB Test Impression события** (показы AB-тестов) + +Все логи используют **console.group** для структурированного отображения и поддерживают цветное форматирование. + +--- + +## 📊 Page View события + +### ✅ Успешная отправка + +``` +▼ [GA] 📊 Page View Event Sent + 🕐 Timestamp: 2025-10-23T19:15:42.123Z + 📍 URL: /soulmate/partner-age + 🌐 Full Location: http://localhost:3000/soulmate/partner-age + 📄 Page Title: Soulmate Portrait - Partner Age + 📦 Payload: { + page_path: "/soulmate/partner-age", + page_location: "http://localhost:3000/soulmate/partner-age", + page_title: "Soulmate Portrait - Partner Age" + } + ✅ Status: Successfully sent to Google Analytics +``` + +### ⚠️ Google Analytics не доступен + +``` +⚠️ [GA] ⚠️ Page View NOT Sent + Reason: Google Analytics not available (window.gtag is undefined) +``` + +--- + +## 🧪 AB Test Impression события + +### ✅ Успешная отправка (первый раз) + +``` +▼ [GA] 🧪 AB Test Impression Event Sent + 🕐 Timestamp: 2025-10-23T19:15:42.456Z + 🏷️ Flag: soulmate-onboarding-image + 🎯 Variant: v1 + 📦 Event Name: experiment_impression + 📦 Payload: { + app_name: "witlab-funnel", + feature: "soulmate-onboarding-image", + treatment: "v1" + } + 💾 Storage Key: unleash_impression_soulmate-onboarding-image_v1 + ✅ Status: Successfully sent to Google Analytics + 🔍 Verify in Network tab: Look for /g/collect requests +``` + +### ⚠️ Пропущено (уже отправлялось) + +``` +▼ [GA] 🧪 AB Test Impression SKIPPED (Already Sent) + 🕐 Timestamp: 2025-10-23T19:16:10.789Z + 🏷️ Flag: soulmate-onboarding-image + 🎯 Variant: v1 + 💾 Storage Key: unleash_impression_soulmate-onboarding-image_v1 + ⚠️ Reason: Already sent in this session + 📊 Check sessionStorage to verify +``` + +### ⚠️ Пропущено (невалидный вариант) + +``` +▼ [GA] 🧪 AB Test Impression SKIPPED + 🕐 Timestamp: 2025-10-23T19:15:40.123Z + 🏷️ Flag: some-test-flag + 🎯 Variant: disabled + ⚠️ Reason: Invalid variant (disabled or undefined) +``` + +### ❌ Ошибка (GA не загружен) + +``` +▼ [GA] 🧪 AB Test Impression NOT Sent + 🕐 Timestamp: 2025-10-23T19:15:42.456Z + 🏷️ Flag: soulmate-trial-grid + 🎯 Variant: grid + ❌ Error: Google Analytics not available (window.gtag is undefined) + 💡 Solution: Check that GoogleAnalytics component is loaded with measurementId +``` + +--- + +## 🧹 Очистка истории AB-тестов + +``` +▼ [GA] 🧪 AB Test Impressions Cleared + 🕐 Timestamp: 2025-10-23T19:20:15.234Z + 🧹 Keys Removed: 2 + 📋 Removed Keys: [ + "unleash_impression_soulmate-onboarding-image_v1", + "unleash_impression_soulmate-trial-grid_grid" + ] + ✅ Status: All AB test impression history cleared + 💡 New impressions will be sent on next screen view +``` + +--- + +## 📋 Yandex Metrika события + +### ✅ Успешная отправка + +``` +▼ [YM] 📊 Page View Event Sent + 🕐 Timestamp: 2025-10-23T19:15:42.123Z + 📍 URL: /soulmate/partner-age + 🔢 Counter ID: 104471567 + ✅ Status: Successfully sent to Yandex Metrika +``` + +### ⚠️ Counter ID не найден + +``` +⚠️ [YM] ⚠️ Page View NOT Sent + Reason: Counter ID not found +``` + +--- + +## 🎨 Цветовая схема + +Логи используют цветовое кодирование для быстрой идентификации: + +| Тип события | Цвет | Значок | +|-------------|------|--------| +| **GA Page View** | 🔵 Синий (`#4285F4`) | 📊 | +| **YM Page View** | 🔴 Красный (`#FF0000`) | 📊 | +| **AB Test Sent** | 🔵 Синий (`#4285F4`) | 🧪 | +| **AB Test Skipped** | ⚪ Серый (`#9E9E9E`) | 🧪 | +| **AB Test Cleared** | 🟠 Оранжевый (`#FF9800`) | 🧪 | +| **Warnings** | 🟡 Желтый (`#FFA500`) | ⚠️ | +| **Errors** | 🔴 Красный (`#FF0000`) | ❌ | + +--- + +## 🔍 Как использовать + +### 1. Открыть DevTools Console + +``` +Chrome/Edge: F12 → Console tab +Firefox: F12 → Console tab +Safari: Cmd+Option+C +``` + +### 2. Просмотреть события + +Все события логируются **автоматически**: + +- При каждом переходе между экранами → **Page View** +- При попадании на экран с AB-тестом → **AB Test Impression** + +### 3. Развернуть группу + +Клик на `▼` (или стрелку) чтобы увидеть детали: + +``` +▼ [GA] 📊 Page View Event Sent ← Клик здесь + 🕐 Timestamp: ... + 📍 URL: ... + ... +``` + +### 4. Проверить Network Tab + +После каждого лога проверьте Network tab: + +``` +DevTools → Network → Filter: "collect" + +Должны появиться POST запросы: +POST /g/collect?v=2&tid=G-XXX&en=page_view... +POST /g/collect?v=2&tid=G-XXX&en=experiment_impression... +``` + +### 5. Проверить sessionStorage + +```javascript +// В консоли браузера: +Object.keys(sessionStorage) + .filter(key => key.startsWith("unleash_impression_")) + .forEach(key => console.log(key, sessionStorage.getItem(key))); + +// Вывод: +// unleash_impression_soulmate-onboarding-image_v1 "true" +// unleash_impression_soulmate-trial-grid_grid "true" +``` + +--- + +## 🧪 Тестирование AB-тестов + +### Очистить историю и переотправить + +```javascript +// В консоли браузера: +import { clearUnleashImpressions } from "@/lib/funnel/unleash"; + +// Очистить все impression события +clearUnleashImpressions(); + +// Перезагрузить страницу +window.location.reload(); + +// События отправятся заново! +``` + +### Вручную проверить ключи sessionStorage + +```javascript +// Посмотреть все AB test ключи: +Object.keys(sessionStorage) + .filter(key => key.startsWith("unleash_impression_")); + +// Удалить конкретный ключ: +sessionStorage.removeItem("unleash_impression_soulmate-onboarding-image_v1"); + +// Удалить все impression ключи: +Object.keys(sessionStorage) + .filter(key => key.startsWith("unleash_impression_")) + .forEach(key => sessionStorage.removeItem(key)); +``` + +--- + +## 📊 Пример полного flow + +### Сценарий: Пользователь проходит воронку Soulmate + +``` +1. Открытие /soulmate/onboarding + ↓ + [GA] 📊 Page View Event Sent + 🕐 2025-10-23T19:15:40.000Z + 📍 /soulmate/onboarding + + [GA] 🧪 AB Test Impression Event Sent + 🏷️ soulmate-onboarding-image + 🎯 v1 + +2. Переход на /soulmate/gender + ↓ + [GA] 📊 Page View Event Sent + 🕐 2025-10-23T19:16:05.000Z + 📍 /soulmate/gender + +3. Переход на /soulmate/partner-age + ↓ + [GA] 📊 Page View Event Sent + 🕐 2025-10-23T19:16:30.000Z + 📍 /soulmate/partner-age + +...18 экранов спустя... + +4. Переход на /soulmate/email + ↓ + [GA] 📊 Page View Event Sent + 🕐 2025-10-23T19:20:15.000Z + 📍 /soulmate/email + + [GA] 🧪 AB Test Impression Event Sent + 🏷️ soulmate-trial-grid + 🎯 grid + +5. Возврат назад на /soulmate/onboarding + ↓ + [GA] 📊 Page View Event Sent + 🕐 2025-10-23T19:21:00.000Z + 📍 /soulmate/onboarding + + [GA] 🧪 AB Test Impression SKIPPED (Already Sent) + 🏷️ soulmate-onboarding-image + 🎯 v1 + ⚠️ Already sent in this session +``` + +--- + +## 🎯 Преимущества новых логов + +### ✅ Уверенность в отправке + +Теперь вы **точно видите**: +- ✅ Событие отправлено в GA +- ⏰ Когда именно (timestamp) +- 📦 Какие данные (payload) +- 💾 Сохранено в sessionStorage + +### ✅ Легкая отладка + +При проблемах сразу видно: +- ❌ GA не загружен +- ⚠️ Событие уже отправлялось +- ⚠️ Невалидный вариант AB-теста + +### ✅ Удобная навигация + +- Логи сгруппированы (не захламляют консоль) +- Цветное кодирование для быстрой идентификации +- Эмодзи для визуальных маркеров + +### ✅ Полная трассируемость + +Каждый лог содержит: +- 🕐 Timestamp (ISO 8601) +- 📍 URL / Flag / Variant +- 📦 Полный payload +- ✅ Статус отправки +- 💡 Подсказки при ошибках + +--- + +## 🔗 Связанные документы + +- `GA_AB_TEST_ANALYSIS.md` - Техническая документация системы +- `SOULMATE_AB_TESTS_TIMELINE.md` - Детальный анализ AB-тестов Soulmate +- `SOULMATE_AB_QUICK_REFERENCE.md` - Быстрая справка по AB-тестам + +--- + +## 📝 Примечания + +### Production vs Development + +Логи работают **в обоих режимах**: +- **Development**: Все логи показываются +- **Production**: Все логи показываются (для проверки в реальном времени) + +Если нужно отключить логи в production, можно обернуть в условие: + +```typescript +if (process.env.NODE_ENV === "development") { + console.groupCollapsed(...); +} +``` + +### Производительность + +**console.groupCollapsed** не влияет на производительность: +- Группа свернута по умолчанию +- Содержимое вычисляется только при раскрытии +- Минимальный overhead + +### Browser Support + +Логи работают во всех современных браузерах: +- ✅ Chrome/Edge (полная поддержка) +- ✅ Firefox (полная поддержка) +- ✅ Safari (полная поддержка, без цветов в groupCollapsed) diff --git a/docs/GA_AB_TEST_ANALYSIS.md b/docs/GA_AB_TEST_ANALYSIS.md new file mode 100644 index 0000000..4e2ede6 --- /dev/null +++ b/docs/GA_AB_TEST_ANALYSIS.md @@ -0,0 +1,375 @@ +# 📊 Анализ Google Analytics и AB-тестов в witlab-funnel + +## 🎯 Краткий ответ + +### Когда отправляется impression событие AB-теста? + +**✅ В момент когда пользователь попадает на экран с AB-тестом** + +- НЕ при загрузке всей воронки +- НЕ при инициализации Unleash +- Именно при рендеринге конкретного экрана в `FunnelRuntime` + +### Где происходит отправка? + +**Файл:** `src/components/funnel/FunnelRuntime.tsx` (строки 136-150) + +```typescript +useEffect(() => { + if (currentScreenFlags.length === 0) return; + + currentScreenFlags.forEach((flag) => { + const variant = activeVariants[flag]; + sendUnleashImpression(flag, variant); // ← ЗДЕСЬ + }); +}, [currentScreenFlags, activeVariants]); +``` + +### Формат события в GA + +```javascript +window.gtag("event", "experiment_impression", { + app_name: "witlab-funnel", + feature: "trial-button-test", + treatment: "v1" +}); +``` + +--- + +## 🏗️ Архитектура + +### Иерархия компонентов + +``` +app/[funnelId]/layout.tsx +├─ UnleashProvider (Unleash SDK) +│ └─ PixelsProvider +│ ├─ GoogleAnalytics ← загружает gtag.js +│ └─ PageViewTracker +│ +└─ FunnelUnleashWrapper ← собирает все флаги воронки + ├─ FlagVariantFetcher[] ← загружает варианты + └─ FunnelRuntime ← отправляет impression когда экран виден +``` + +--- + +## ⏱️ Timeline событий + +``` +T+0ms Пользователь открывает /funnel/payment +T+100ms GoogleAnalytics загружает gtag.js +T+200ms FunnelUnleashWrapper сканирует воронку + Находит флаги: ["trial-button-test", "payment-variant"] +T+300ms Unleash SDK возвращает варианты: + • trial-button-test → "v1" + • payment-variant → "v2" +T+400ms FunnelRuntime монтируется + currentScreen = "payment" + currentScreenFlags = ["trial-button-test"] +T+420ms useEffect срабатывает + ✅ sendUnleashImpression("trial-button-test", "v1") + ✅ window.gtag("event", "experiment_impression", {...}) +T+421ms Событие отправлено в Google Analytics +``` + +**При переходе на следующий экран:** + +``` +T+0ms Клик "Continue" → переход на /funnel/gender +T+100ms currentScreen = "gender" + currentScreenFlags = ["payment-variant"] +T+120ms ✅ sendUnleashImpression("payment-variant", "v2") + ✅ Второе событие отправлено +``` + +**При возврате назад:** + +``` +T+0ms Клик "Back" → возврат на /funnel/payment +T+100ms currentScreen = "payment" + currentScreenFlags = ["trial-button-test"] +T+120ms sendUnleashImpression проверяет sessionStorage + ❌ Уже отправлялось - пропускаем +``` + +--- + +## 🔧 Ключевые компоненты + +### 1. Инициализация Google Analytics + +**Файл:** `src/components/analytics/GoogleAnalytics.tsx` + +```typescript +