gofnnp/w-funnel

Fork 0

dev.daminik00 6c50d05123 ab

2025-10-21 01:27:08 +02:00

11 KiB

Raw Blame History

🧪 AB Testing с Unleash в Воронках

Полное руководство по интеграции AB тестов через Unleash feature flags в систему воронок.

📋 Содержание

Настройка
Примеры использования
API Reference
Архитектура

🔧 Настройка

1. Environment Variables

Добавьте в .env.local:

NEXT_PUBLIC_UNLEASH_URL=https://your-unleash-instance.com/api/frontend
NEXT_PUBLIC_UNLEASH_CLIENT_KEY=your-client-key

Важно: Если переменные не установлены, AB тесты будут отключены автоматически.

2. Настройка Unleash Dashboard

Создайте feature flag в Unleash (например, trial-button-test)
Добавьте варианты (v0, v1, v2, etc.)
Настройте stickiness на sessionId для консистентности
Добавьте gradual rollout strategy

💡 Примеры использования

Пример 1: AB тест текста кнопки

Сценарий: Тестируем разные тексты кнопки оплаты

{
  "id": "payment-screen",
  "template": "trialPayment",
  "bottomActionButton": {
    "text": "Continue"
  },
  "variants": [
    {
      "conditions": [
        {
          "screenId": "payment-screen",
          "conditionType": "unleash",
          "unleashFlag": "trial-button-test",
          "unleashVariants": ["v1"],
          "operator": "includesAny"
        }
      ],
      "overrides": {
        "bottomActionButton": {
          "text": "Start 3-Day Trial"
        }
      }
    },
    {
      "conditions": [
        {
          "screenId": "payment-screen",
          "conditionType": "unleash",
          "unleashFlag": "trial-button-test",
          "unleashVariants": ["v2"],
          "operator": "includesAny"
        }
      ],
      "overrides": {
        "bottomActionButton": {
          "text": "Get My Reading Now"
        }
      }
    }
  ]
}

Результат:

v0 (контроль): "Continue"
v1: "Start 3-Day Trial"
v2: "Get My Reading Now"

Пример 2: AB тест навигации

Сценарий: Тестируем короткий vs длинный onboarding

{
  "id": "gender-select",
  "template": "list",
  "navigation": {
    "defaultNextScreenId": "birthdate",
    "rules": [
      {
        "conditions": [
          {
            "screenId": "gender-select",
            "conditionType": "unleash",
            "unleashFlag": "onboarding-flow-test",
            "unleashVariants": ["short"],
            "operator": "equals"
          }
        ],
        "nextScreenId": "payment"
      },
      {
        "conditions": [
          {
            "screenId": "gender-select",
            "conditionType": "unleash",
            "unleashFlag": "onboarding-flow-test",
            "unleashVariants": ["long"],
            "operator": "equals"
          }
        ],
        "nextScreenId": "relationship-status"
      }
    ]
  }
}

Результат:

v0/default: gender → birthdate
short: gender → payment (пропускаем шаги)
long: gender → relationship-status → ... → payment

Пример 3: Комбинированные условия

Сценарий: AB тест только для женской аудитории

{
  "variants": [
    {
      "conditions": [
        {
          "screenId": "gender",
          "conditionType": "options",
          "optionIds": ["female"],
          "operator": "includesAny"
        },
        {
          "screenId": "payment",
          "conditionType": "unleash",
          "unleashFlag": "female-specific-test",
          "unleashVariants": ["v1"],
          "operator": "equals"
        }
      ],
      "overrides": {
        "title": {
          "text": "Special offer for you! ✨"
        }
      }
    }
  ]
}

📚 API Reference

NavigationConditionDefinition

interface NavigationConditionDefinition {
  screenId: string;
  conditionType?: "options" | "values" | "unleash";
  operator?: "includesAny" | "includesAll" | "includesExactly" | "equals";
  
  // Для Unleash AB тестов
  unleashFlag?: string;
  unleashVariants?: string[];
  
  // Для других типов
  optionIds?: string[];
  values?: string[];
}

Операторы

Оператор	Описание	Пример
`includesAny`	Хотя бы один вариант совпадает	`["v1", "v2"]` → true если v1 ИЛИ v2
`includesAll`	Все варианты совпадают	`["v1"]` → true если v1 (для одного = includesAny)
`includesExactly`	Только указанные варианты	Редко используется
`equals`	Точное совпадение	`["v1"]` → true только если v1

Типы условий

Тип	Использование	Пример
`options`	List экраны	`{ conditionType: "options", optionIds: ["male"] }`
`values`	Зодиак, возраст	`{ conditionType: "values", values: ["aries", "leo"] }`
`unleash`	AB тесты	`{ conditionType: "unleash", unleashFlag: "test-1" }`

🏗 Архитектура

Компоненты

UnleashProvider (от @unleash/proxy-client-react)
  └── FunnelUnleashWrapper (собирает все флаги из воронки)
      └── UnleashContextProvider (предоставляет активные варианты)
          └── FunnelRuntime (использует варианты для navigation/variants)

Поток данных

FunnelUnleashWrapper сканирует все экраны воронки
Находит все unleashFlag в conditions
Получает варианты для всех флагов через useVariant
Передает { flagName: variant } в UnleashContextProvider
FunnelRuntime использует unleashChecker для проверки условий
navigation.ts и variants.ts вызывают unleashChecker при проверке

Файловая структура

src/
├── lib/funnel/
│   ├── unleash/
│   │   ├── UnleashProvider.tsx       # Wrapper для Unleash SDK
│   │   ├── UnleashContext.tsx        # Context с активными вариантами
│   │   ├── useUnleash.ts             # Hook для получения вариантов
│   │   └── index.ts
│   ├── navigation.ts                 # Поддержка unleash в условиях
│   ├── variants.ts                   # Поддержка unleash в вариантах
│   └── types.ts                      # Расширенные типы
├── components/
│   ├── funnel/
│   │   ├── FunnelUnleashWrapper.tsx  # Сборщик флагов
│   │   └── FunnelRuntime.tsx         # Интеграция unleashChecker
│   └── admin/builder/forms/
│       ├── UnleashConditionEditor.tsx      # UI для настройки
│       ├── ConditionTypeSelector.tsx       # Выбор типа
│       └── variants/
│           └── VariantConditionEditor.tsx  # Интеграция в существующий UI

🎯 Best Practices

1. Naming Convention

# Формат: [page]-[element]-[description]
trial-button-text
onboarding-flow-length
payment-copy-variant

2. Variants Naming

# Всегда используйте v0 как контроль
v0 - контрольная группа (baseline)
v1 - вариант 1
v2 - вариант 2

3. Stickiness

Всегда используйте sessionId для stickiness в Unleash:

Обеспечивает консистентность для анонимных пользователей
Пользователь видит одинаковый вариант на всех экранах
Не требует авторизации

4. Rollout Strategy

# Начните с малого
Week 1: 10% traffic → v1
Week 2: 50% traffic → v1
Week 3: 100% traffic → v1 (если winner)

🔍 Debugging

Development Mode

В development режиме в консоли будут логи:

[Unleash] Flag "trial-button-test" = v1
[Unleash] Active variants: { "trial-button-test": "v1", "onboarding-flow": "short" }

Query Parameters (только dev)

# Переопределить вариант флага
?trial-button-test=v2

# Комбинировать несколько
?trial-button-test=v1&onboarding-flow=short

Admin Preview

В админке конструктора:

Экраны с AB тестами помечены значком 🧪
В превью можно переключать варианты
Validation показывает некорректные флаги

⚠️ Troubleshooting

Флаг не работает

Проверьте:

✅ Environment variables установлены
✅ Флаг создан в Unleash Dashboard
✅ Флаг включен (enabled)
✅ Правильно указано unleashFlag в JSON
✅ Варианты существуют в Unleash

Всегда показывается контроль

Причины:

Rollout = 0% (увеличьте в Unleash)
Неправильный stickiness (используйте sessionId)
Constraints блокируют пользователя

Ошибка в консоли

Cannot find module '@/lib/funnel/unleash'

Решение: Проект не собран. Выполните npm run dev

📊 Analytics Integration

Unleash автоматически отправляет impression events:

window.gtag?.("event", "experiment_impression", {
  app_name: "witlab-funnel",
  feature: "trial-button-test",
  treatment: "v1"
});

Интегрируется с:

✅ Google Analytics
✅ Google Tag Manager
✅ Yandex Metrika (через funnel meta)

🚀 Deployment

Перед выкаткой

# 1. Проверьте сборку
npm run build

# 2. Проверьте все флаги в Unleash
# 3. Убедитесь что rollout = 0% для новых тестов
# 4. Deploy

После выкатки

# 1. Проверьте метрики через 1 час
# 2. Постепенно увеличивайте rollout
# 3. Анализируйте результаты через 1-2 недели
# 4. Выберите winner и удалите проигравшие варианты

📞 Support

Вопросы? Проверьте:

Эту документацию
Примеры в /public/funnels/
Код в /src/lib/funnel/unleash/

Нашли баг? Создайте issue с:

Название флага
JSON конфигурация
Ожидаемое vs фактическое поведение

11 KiB Raw Blame History Unescape Escape