📈 API: Удержание
Когортный анализ, метрики возвращаемости и жизненный цикл клиентов
Удержание (Retention) показывает, какой процент пользователей возвращается в ваш продукт после первого визита. Это ключевая метрика для оценки качества продукта и долгосрочной ценности клиентов.
Основные понятия
Когорта
Группа пользователей, объединенных по времени первого визита (например, все пользователи, пришедшие 1 марта 2026).
Retention (Удержание)
Процент пользователей из когорты, которые вернулись в определенный день. Например, Retention Day 7 показывает, сколько пользователей вернулись на 7-й день после первого визита.
LTV (Lifetime Value)
Прогнозируемая прибыль, которую принесет клиент за все время использования продукта. Рассчитывается на основе удержания и среднего чека.
Визуализация удержания
График удержания
График показывает динамику удержания для ключевых дней (1, 7, 30) по последним когортам:
Когортная таблица
Классическое представление удержания, где каждая строка — когорта, а столбцы — дни жизни:
🟢 Высокое (>40%) 🟡 Среднее (20-40%) 🔴 Низкое (<20%)
Эндпоинты
1. Получение данных удержания
GET /api/retention?cohort_from=...&cohort_to=... — данные для построения когортной таблицы и графика удержания.
Параметры запроса
| Параметр | Описание | По умолчанию |
|---|---|---|
cohort_from |
Начальная дата для когорт (YYYY-MM-DD) | -30 дней |
cohort_to |
Конечная дата для когорт (YYYY-MM-DD) | сегодня |
app_id |
Фильтр по приложению | все приложения |
Пример запроса
curl -X GET "https://api.instantbase.online/api/retention?cohort_from=2026-03-01&cohort_to=2026-03-19" \
-H "Cookie: session_id=ваша_сессия"Пример ответа
{
"cohorts": {
"2026-03-01": {
"total": 245,
"days": {
"0": 100,
"1": 42.5,
"2": 35.2,
"3": 32.1,
"4": 30.0,
"5": 28.4,
"6": 27.1,
"7": 26.3,
"14": 21.5,
"30": 18.2
}
},
"2026-03-02": {
"total": 312,
"days": {
"0": 100,
"1": 45.1,
"2": 38.4,
"3": 34.2,
"4": 31.5,
"5": 29.8,
"6": 27.6,
"7": 25.9
}
}
},
"period": {
"from": "2026-03-01",
"to": "2026-03-19"
}
}Структура ответа
| Поле | Описание |
|---|---|
cohorts[date].total |
Общее количество пользователей в когорте |
cohorts[date].days[day] |
Процент удержания в указанный день |
2. Получение агрегированных метрик удержания
GET /api/retention/summary?from=...&to=... — сводные метрики удержания за период.
Пример ответа
{
"success": true,
"retention_day1": 43.2,
"retention_day7": 26.5,
"retention_day30": 17.8,
"retention_day90": 9.3,
"average_lifetime_days": 24.5,
"ltv": 3240.50
}| Поле | Описание |
|---|---|
retention_day1 |
Среднее удержание на следующий день |
retention_day7 |
Среднее удержание через неделю |
retention_day30 |
Среднее удержание через месяц |
average_lifetime_days |
Средняя продолжительность жизни клиента |
ltv |
Прогнозируемая пожизненная ценность |
Интерпретация метрик удержания
| Показатель | Отлично | Хорошо | Средне | Плохо |
|---|---|---|---|---|
| Retention Day 1 | >50% | 40-50% | 30-40% | <30% |
| Retention Day 7 | >30% | 20-30% | 15-20% | <15% |
| Retention Day 30 | >20% | 15-20% | 10-15% | <10% |
Фильтрация по приложениям
Ко всем эндпоинтам можно добавить параметр app_id для фильтрации данных по конкретному приложению:
GET /api/retention?cohort_from=2026-03-01&cohort_to=2026-03-19&app_id=13Это позволяет сравнивать удержание в разных приложениях или версиях.
Расчет LTV (Lifetime Value)
LTV рассчитывается по формуле:
LTV = (Средний чек × Частота покупок) × (1 / Отток) × МаржинальностьИли на основе когорт:
LTV = Сумма(Выручка_по_когорте) / Размер_когортыПримеры использования
Получение данных для графика удержания
async function getRetentionData() {
const response = await fetch('/api/retention?cohort_from=2026-03-01&cohort_to=2026-03-19', {
credentials: 'include'
});
const data = await response.json();
// Подготовка данных для графика
const cohorts = Object.keys(data.cohorts).sort();
const day1Data = cohorts.map(date => data.cohorts[date].days[1] || 0);
const day7Data = cohorts.map(date => data.cohorts[date].days[7] || 0);
const day30Data = cohorts.map(date => data.cohorts[date].days[30] || 0);
return { cohorts, day1Data, day7Data, day30Data };
}Сравнение удержания двух приложений
async function compareRetention(app1, app2) {
const [data1, data2] = await Promise.all([
fetch(`/api/retention?app_id=${app1}`).then(r => r.json()),
fetch(`/api/retention?app_id=${app2}`).then(r => r.json())
]);
const avgRetention1 = calculateAverageRetention(data1);
const avgRetention2 = calculateAverageRetention(data2);
console.log(`Приложение 1: ${avgRetention1}%`);
console.log(`Приложение 2: ${avgRetention2}%`);
}Рекомендации по улучшению удержания
- Анализируйте "точки отвала" — дни, когда удержание резко падает
- Сравнивайте когорты — улучшается ли удержание со временем?
- Сегментируйте пользователей — удержание может сильно отличаться по каналам трафика
- Используйте метаданные — отмечайте активации и ключевые события
- Запускайте реактивационные кампании — для пользователей, которые перестали возвращаться
Когортный анализ по неделям и месяцам
Для долгосрочного анализа можно группировать когорты по неделям или месяцам:
| Тип периода | Когда использовать |
|---|---|
| Дневные когорты | Для высокочастотных продуктов (соцсети, игры, мессенджеры) |
| Недельные когорты | Для регулярных сервисов (доставка еды, фитнес-приложения) |
| Месячные когорты | Для подписочных сервисов, B2B, интернет-магазинов |
В текущей версии API поддерживаются дневные когорты. Для недельных и месячных используйте агрегацию на стороне клиента.
Коды ошибок
| Код | Описание | Решение |
|---|---|---|
| 400 | Invalid date format | Проверьте формат дат (YYYY-MM-DD) |
| 400 | Application not found | Проверьте переданный app_id |
| 401 | Unauthorized | Требуется авторизация через сессию |
| 500 | Internal server error | Повторите запрос позже |
Примеры для разных типов бизнеса
Интернет-магазин
Хорошее удержание: Day 1 → 30%, Day 7 → 15%, Day 30 → 8%
SaaS-сервис
Хорошее удержание: Day 1 → 50%, Day 7 → 35%, Day 30 → 25%
Мобильная игра
Хорошее удержание: Day 1 → 45%, Day 7 → 25%, Day 30 → 12%
Что дальше?
Нужна помощь с анализом удержания?
Напишите нам, и мы поможем интерпретировать метрики