w-funnel/docs/UNLEASH_SETUP.md

# 🚀 Unleash AB Testing - Quick Start

## ✅ Что реализовано

### 1. Типы и интерфейсы
- ✅ Расширен `NavigationConditionDefinition` с полями `unleashFlag` и `unleashVariants`
- ✅ Добавлен тип условия `"unleash"` наравне с `"options"` и `"values"`
- ✅ Полная типизация для TypeScript

### 2. Unleash SDK интеграция
- ✅ Установлен `@unleash/proxy-client-react`
- ✅ Создан `UnleashProvider` с настройками для воронок
- ✅ `UnleashContextProvider` для передачи активных вариантов
- ✅ `FunnelUnleashWrapper` автоматически собирает все флаги из воронки

### 3. Логика проверки условий
- ✅ `navigation.ts` поддерживает Unleash условия
- ✅ `variants.ts` поддерживает Unleash условия
- ✅ Функция `unleashChecker` передается через всю цепочку
- ✅ Работает для навигации И для вариантов экранов

### 4. UI в админке конструктора
- ✅ `ConditionTypeSelector` - выбор типа условия
- ✅ `UnleashConditionEditor` - полноценный редактор AB тестов
- ✅ Интегрировано в `VariantConditionEditor`
- ✅ Поддержка всех операторов (includesAny, equals, etc.)

### 5. Документация
- ✅ Полное руководство `AB_TESTING_GUIDE.md`
- ✅ Примеры использования
- ✅ API Reference
- ✅ Best practices

## 🏁 Быстрый старт

### Шаг 1: Настройте Unleash

Создайте `.env.local`:

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

### Шаг 2: Создайте флаг в Unleash Dashboard

1. Перейдите в Unleash Dashboard
2. Создайте новый feature flag: `button-text-test`
3. Добавьте варианты:
   - v0 (контроль) - 50%
   - v1 - 25%
   - v2 - 25%
4. Включите gradual rollout strategy
5. Установите stickiness = `sessionId`

### Шаг 3: Добавьте AB тест в воронку

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

1. Откройте экран для редактирования
2. Перейдите в секцию "Вариативность"
3. Добавьте вариант
4. Выберите тип условия: **AB тест (Unleash)**
5. Укажите:
   - Название флага: `button-text-test`
   - Ожидаемые варианты: `v1`
   - Оператор: `Равен (один вариант)`
6. Настройте overrides (например, текст кнопки)
7. Сохраните воронку

### Шаг 4: Тестируйте

```bash
npm run dev
```

Откройте воронку в разных вкладках - вы увидите разные варианты!

## 📁 Структура файлов

```
Новые файлы:
├── src/lib/funnel/unleash/
│   ├── UnleashProvider.tsx          # Provider для Unleash SDK
│   ├── UnleashContext.tsx           # Context с активными вариантами
│   ├── useUnleash.ts                # Хук для работы с флагами
│   └── index.ts
├── src/components/funnel/
│   └── FunnelUnleashWrapper.tsx     # Сборщик всех флагов
├── src/components/admin/builder/forms/
│   ├── UnleashConditionEditor.tsx   # UI редактор AB тестов
│   └── ConditionTypeSelector.tsx    # Селектор типа условия
├── AB_TESTING_GUIDE.md              # Полное руководство
├── UNLEASH_SETUP.md                 # Этот файл
└── public/funnels/
    └── ab-test-example.json         # Пример воронки с AB тестами

Модифицированные файлы:
├── src/lib/funnel/
│   ├── types.ts                     # ✏️ Добавлены поля для Unleash
│   ├── navigation.ts                # ✏️ Поддержка Unleash условий
│   └── variants.ts                  # ✏️ Поддержка Unleash условий
├── src/components/funnel/
│   └── FunnelRuntime.tsx            # ✏️ Интеграция unleashChecker
├── src/components/admin/builder/forms/variants/
│   └── VariantConditionEditor.tsx   # ✏️ Добавлен UI для Unleash
├── src/app/[funnelId]/[screenId]/
│   └── page.tsx                     # ✏️ Обернут в Unleash Provider
└── package.json                     # ✏️ Добавлен @unleash/proxy-client-react
```

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

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

```json
{
  "id": "payment",
  "template": "trialPayment",
  "bottomActionButton": {
    "text": "Continue"
  },
  "variants": [
    {
      "conditions": [
        {
          "screenId": "payment",
          "conditionType": "unleash",
          "unleashFlag": "button-text-test",
          "unleashVariants": ["v1"],
          "operator": "equals"
        }
      ],
      "overrides": {
        "bottomActionButton": {
          "text": "Start Trial"
        }
      }
    }
  ]
}
```

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

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

## 🧪 Тестовая воронка

Готовая тестовая воронка: `/public/funnels/ab-test-example.json`

Запустите:
```bash
npm run dev
# Откройте: http://localhost:3000/ab-test-example/welcome
```

## ✨ Возможности

### Что можно тестировать:

- ✅ **Тексты** (заголовки, подзаголовки, кнопки)
- ✅ **Навигацию** (разные пути через воронку)
- ✅ **Контент** (иконки, описания, блоки)
- ✅ **Комбинации** (AB тест + пол + возраст)
- ✅ **Любые поля** экрана через variants

### Операторы:

- `includesAny` - хотя бы один вариант
- `includesAll` - все варианты
- `includesExactly` - точно эти варианты
- `equals` - равен (один вариант)

### Типы условий:

- `options` - выбор из списка
- `values` - конкретные значения (зодиак, возраст)
- `unleash` - AB тесты через Unleash

## 🔧 Требования

- Node.js 18+
- Next.js 15
- Unleash instance (или Unleash Cloud)
- React 19

## 📚 Дополнительная документация

- **AB_TESTING_GUIDE.md** - Полное руководство с примерами
- **Unleash Docs** - https://docs.getunleash.io/
- **Примеры воронок** - `/public/funnels/`

## 🐛 Troubleshooting

### Флаги не работают?

1. Проверьте `.env.local` - переменные должны быть установлены
2. Проверьте Unleash Dashboard - флаг должен быть включен
3. Проверьте rollout - должен быть > 0%
4. Проверьте консоль браузера - должны быть логи Unleash

### Ошибка импорта?

```bash
npm install
npm run dev
```

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

- Увеличьте rollout в Unleash
- Проверьте stickiness = sessionId
- Откройте в новой вкладке (новая сессия)

## 🎉 Готово!

AB тестирование полностью интегрировано и готово к использованию!

**Следующие шаги:**
1. Настройте Unleash
2. Создайте первый флаг
3. Добавьте AB тест в воронку
4. Анализируйте результаты
5. Выбирайте победителя!