ads-reporter

1. Дневные отчеты - today vs yesterday с today-компенсацией
2. Недельные отчеты - агрегированные данные с трендами
3. Multi-period анализ - данные за 5 периодов
4. Health Score - 5-компонентный расчёт в отчётах
5. Сравнение периодов - week-over-week, month-over-month
6. Custom отчеты - по запросу пользователя

---

Multi-period сбор (5 периодов)

ВАЖНО: Для полного отчёта собирай данные за все периоды!

```python

# Параллельный сбор данных

today = get_insights(object_id="act_XXX", time_range="today", level="adset")

yesterday = get_insights(object_id="act_XXX", time_range="yesterday", level="adset")

last_3d = get_insights(object_id="act_XXX", time_range="last_3d", level="adset")

last_7d = get_insights(object_id="act_XXX", time_range="last_7d", level="adset")

last_30d = get_insights(object_id="act_XXX", time_range="last_30d", level="adset")

# Для детализации по ads

ads_yesterday = get_insights(object_id="act_XXX", time_range="yesterday", level="ad")

```

Доступные периоды

| Значение | Описание | Использование |

|----------|----------|---------------|

| today | Сегодня | Today-компенсация |

| yesterday | Вчера | Основной CPL Gap |

| last_3d | Последние 3 дня | Тренд 3d vs 7d |

| last_7d | Последние 7 дней | Тренд 7d vs 30d |

| last_14d | Последние 14 дней | Week-over-week |

| last_30d | Последние 30 дней | Месячный анализ |

| this_month | Текущий месяц | Отчет за месяц |

| last_month | Прошлый месяц | Month-over-month |

| {"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"} | Custom | Любой период |

Уровни агрегации

| Level | Описание |

|-------|----------|

| account | Весь аккаунт |

| campaign | По кампаниям |

| adset | По adsets |

| ad | По объявлениям |

Breakdowns

| Breakdown | Описание |

|-----------|----------|

| age | По возрасту |

| gender | По полу |

| country | По странам |

| device_platform | По устройствам |

| publisher_platform | По площадкам (FB/IG/AN) |

---

Дневной отчет (с today vs yesterday)

```markdown

# Дневной отчет: {Account Name}

📅 {Date}

🎯 Целевой CPL: ${target}

| Метрика | Сейчас | Темп к вчера |

|---------|-------:|--------------|

| Spend | ${X} | {X}% от вчера |

| Leads | {Y} | {comparison} |

| eCPL | ${Z} | {vs yesterday} |

| Impressions | {W} | {X}% от вчера |

| Метрика | Значение | vs Позавчера | vs 7d avg |

|---------|----------|--------------|-----------|

| Spend | ${X} | {+/-}% | {+/-}% |

| Impressions | {Y} | {+/-}% | {+/-}% |

| Leads | {Z} | {+/-}% | {+/-}% |

| CPL | ${A} | {+/-}% | {+/-}% |

| CTR | {B}% | {+/-}pp | {+/-}pp |

{если today.impressions >= 300}:

• eCPL today: ${X}
• eCPL yesterday: ${Y}
• Соотношение: {ratio}

{если лучше}: ✅ Улучшение на {X}%, учтено в Health Score

{если хуже}: ⚠️ Пока хуже, мониторим

| AdSet | HS | Класс | CPL Y | vs Target | CTR | Trend | Today | Action |

|-------|---:|-------|------:|-----------|----:|-------|-------|--------|

| {name} | +45 | very_good | $2.50 | -38% | 1.5% | ↑ | +15 | Scale +30% |

| {name} | +12 | good | $3.80 | -5% | 1.2% | → | - | Hold |

| {name} | -8 | sl_bad | $5.20 | +30% | 0.8% | ↓ | - | Reduce -30% |

| {name} | -35 | bad | $12.00 | +200% | 0.4% | ↓↓ | +20 | Monitor |

1. {ad_name} - CPL ${X}, {Y} leads, Risk {R}
2. {ad_name} - CPL ${X}, {Y} leads, Risk {R}

• {issue1}
• {issue2}

```

---

Недельный отчет (с трендами)

```markdown

# Недельный отчет: {Account Name}

📅 {Start Date} - {End Date}

🎯 Целевой CPL: ${target}

| Метрика | Эта неделя | Прошлая | Изменение | Тренд |

|---------|------------|---------|-----------|-------|

| Spend | ${X} | ${Y} | {+/-}% | {↑/↓/→} |

| Impressions | {X} | {Y} | {+/-}% | {↑/↓/→} |

| Leads | {X} | {Y} | {+/-}% | {↑/↓/→} |

| CPL | ${X} | ${Y} | {+/-}% | {↑/↓/→} |

| CTR | {X}% | {Y}% | {+/-}pp | {↑/↓/→} |

| ROAS | {X}x | {Y}x | {+/-}% | {↑/↓/→} |

| День | Spend | Leads | CPL | vs Target | Trend |

|------|------:|------:|----:|-----------|-------|

| Пн | ${X} | {Y} | ${Z} | {+/-}% | - |

| Вт | ${X} | {Y} | ${Z} | {+/-}% | {vs Пн} |

| Ср | ${X} | {Y} | ${Z} | {+/-}% | {vs Вт} |

| Чт | ${X} | {Y} | ${Z} | {+/-}% | {vs Ср} |

| Пт | ${X} | {Y} | ${Z} | {+/-}% | {vs Чт} |

| Сб | ${X} | {Y} | ${Z} | {+/-}% | {vs Пт} |

| Вс | ${X} | {Y} | ${Z} | {+/-}% | {vs Сб} |

| AdSet | HS | CPL Gap | Trends | Diag | Today | VF | Класс | Action |

|-------|---:|--------:|-------:|-----:|------:|---:|-------|--------|

| {name} | +52 | +45 | +7.5 | 0 | 0 | 1.0 | very_good | Scale |

| {name} | +12 | +30 | -7.5 | -8 | 0 | 0.9 | good | Hold |

| {name} | -22 | -30 | -7.5 | -8 | +20 | 1.0 | sl_bad | Monitor |

AdSet "{name}" (HS = -22):

| Компонент | Значение | Причина |

|-----------|----------|---------|

| CPL Gap | -30 | CPL $5.20 vs target $4, +30% |

| Trends | -7.5 | 3d хуже 7d на 12% |

| CTR Penalty | -8 | CTR 0.8% < 1% |

| CPM Penalty | 0 | CPM $11 в норме |

| Freq Penalty | 0 | Frequency 1.8 в норме |

| Today Adj | +20 | Сегодня CPL $3.50, на 33% лучше! |

| Volume Factor | x1.0 | 3200 impressions |

| Итого | -22 | HS улучшен благодаря today |

| AdSet | Spend | Leads | CPL | HS | Trend | Action |

|-------|------:|------:|----:|---:|-------|--------|

| {name1} | ${X} | {Y} | ${Z} | +{W} | ↑ | Scale +30% |

| {name2} | ${X} | {Y} | ${Z} | +{W} | ↑ | Scale +20% |

| AdSet | Spend | Leads | CPL | HS | Trend | Today | Action |

|-------|------:|------:|----:|---:|-------|-------|--------|

| {name1} | ${X} | {Y} | ${Z} | -{W} | ↓↓ | +15 | Monitor |

| {name2} | ${X} | {Y} | ${Z} | -{W} | ↓ | - | Reduce |

1. {recommendation1}
2. {recommendation2}
3. {recommendation3}

```

---

Отчет по аудиториям

```markdown

# Анализ аудиторий: {Account Name}

📅 {Period}

| Возраст | Spend | Leads | CPL | vs Target | % бюджета |

|---------|------:|------:|----:|-----------|----------:|

| 18-24 | ${X} | {Y} | ${Z} | {+/-}% | {W}% |

| 25-34 | ... | ... | ... | ... | ... |

| 35-44 | ... | ... | ... | ... | ... |

| 45-54 | ... | ... | ... | ... | ... |

| 55-64 | ... | ... | ... | ... | ... |

| 65+ | ... | ... | ... | ... | ... |

| Пол | Spend | Leads | CPL | vs Target |

|-----|------:|------:|----:|-----------|

| Мужчины | ${X} | {Y} | ${Z} | {+/-}% |

| Женщины | ${X} | {Y} | ${Z} | {+/-}% |

| Площадка | Spend | Leads | CPL | CTR | Trend |

|----------|------:|------:|----:|----:|-------|

| Facebook | ${X} | {Y} | ${Z} | {W}% | {↑/↓/→} |

| Instagram | ... | ... | ... | ... | ... |

| Audience Network | ... | ... | ... | ... | ... |

• Лучшая аудитория: {description}
• Худшая аудитория: {description}
• Рекомендации: {recommendation}

```

---

Шаг 1: Подготовка

```

1. Прочитай .claude/ads-agent/config/ad_accounts.md
2. Прочитай бриф → целевые метрики
3. Определи период отчета

```

Шаг 2: Сбор данных (5 периодов)

```python

# Все 5 периодов параллельно

today = get_insights(object_id="act_XXX", time_range="today", level="adset")

yesterday = get_insights(object_id="act_XXX", time_range="yesterday", level="adset")

last_3d = get_insights(object_id="act_XXX", time_range="last_3d", level="adset")

last_7d = get_insights(object_id="act_XXX", time_range="last_7d", level="adset")

last_30d = get_insights(object_id="act_XXX", time_range="last_30d", level="adset")

```

Шаг 3: Расчет метрик и HS

```python

# CPL

cpl = spend / leads if leads > 0 else None

# CTR

ctr = (clicks / impressions) * 100 if impressions > 0 else 0

# Health Score (5 компонентов)

hs = calculate_health_score(

cpl_yesterday, target_cpl,

cpl_3d, cpl_7d, cpl_30d, # для трендов

ctr, cpm, frequency, # для диагностики

cpl_today, # для today-компенсации

impressions # для volume factor

)

# Изменение

change_pct = ((current - previous) / previous) * 100 if previous > 0 else None

```

Шаг 4: Формирование отчета

Используй шаблоны выше, заполни данными.

Шаг 5: Выводы и рекомендации

На основе анализа добавь:

• Что работает хорошо
• Что требует внимания
• Конкретные рекомендации
• Today-компенсация (если применимо)

---

Week-over-Week

```python

# Эта неделя

this_week = get_insights(object_id="act_XXX", time_range="last_7d")

# Прошлая неделя

last_week = get_insights(

object_id="act_XXX",

time_range={"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"}

)

# Расчет изменения

for metric in ["spend", "leads", "impressions"]:

change = ((this_week[metric] - last_week[metric]) / last_week[metric]) * 100

```

Month-over-Month

```python

this_month = get_insights(object_id="act_XXX", time_range="this_month")

last_month = get_insights(object_id="act_XXX", time_range="last_month")

```

---

Хорошие показатели

| Метрика | Хорошо | Отлично |

|---------|--------|---------|

| CTR | > 1% | > 2% |

| CPL | < target | < 0.7x target |

| Frequency | < 3 | < 2 |

| LP View Rate | > 60% | > 80% |

Тревожные сигналы

| Метрика | Внимание | Критично |

|---------|----------|----------|

| CPL | > 1.5x target | > 2x target |

| Frequency | > 4 | > 7 |

| CTR | < 0.5% | < 0.3% |

| Spend без leads | > $10 | > $20 |

---

| Символ | Значение | Условие |

|--------|----------|---------|

| ↑ | Улучшение | CPL падает / CTR растёт |

| → | Стабильно | Изменение ±10% |

| ↓ | Ухудшение | CPL растёт / CTR падает на 10%+ |

| ↓↓ | Сильное ухудшение | Изменение > 30% |

---

Классификация

| Класс | Диапазон | Иконка |

|-------|----------|--------|

| very_good | >= +25 | 🟢 |

| good | +5..+24 | 🟡 |

| neutral | -5..+4 | ⚪ |

| slightly_bad | -25..-6 | 🟠 |

| bad | <= -25 | 🔴 |

Компоненты (для breakdown)

| Компонент | Диапазон | Что влияет |

|-----------|----------|------------|

| CPL Gap | -45..+45 | Отклонение от target |

| Trends | -15..+15 | 3d vs 7d, 7d vs 30d |

| CTR Penalty | -8..0 | CTR < 1% |

| CPM Penalty | -12..0 | CPM > median * 1.3 |

| Freq Penalty | -10..0 | Frequency > 2 |

| Today Adj | 0..+30 | Хороший today |

| Volume Factor | x0.6..1.0 | Impressions |

---

Позитивные

• "CPL снизился на {X}% благодаря {причина}"
• "Лучшая аудитория - {description}, CPL ${X}"
• "Успешное масштабирование: +{X}% spend при сохранении CPL"
• "Today показывает улучшение: CPL ${X} vs ${Y} вчера"

Негативные

• "CPL вырос на {X}%, основная причина - {adset/ad}"
• "Ad-eater обнаружен: {name}, тратит {X}% бюджета"
• "Frequency {X} - аудитория выгорает"
• "Тренд негативный: 3d хуже 7d на {X}%"

Рекомендации

• "Масштабировать {adset} - HS +{X}, CPL ниже target"
• "Снизить бюджет {adset} - HS {X}, CPL выше нормы"
• "Мониторить {adset} - today показывает улучшение"
• "Обновить креативы - высокая frequency {X}"

---

"Отчет за сегодня"

→ Дневной отчет с today vs yesterday, HS по adsets

"Недельный отчет"

→ Полный отчет с трендами, HS breakdown, рекомендации

"Сравни эту неделю с прошлой"

→ Week-over-week с детальным сравнением

"Анализ по возрастам"

→ Breakdown по age, рекомендации по аудиториям

"Какие adsets лучше всего работают?"

→ Топ по HS, рекомендации по масштабированию