title: Ads Analyzer Team — Research (design phase)
type: research
parent: ad-analytics-hub
status: design-phase (specification before implementation)
last_updated: 2026-05-11
author: VPS Claude + WebSearch
Ads Analyzer Team — Research для CrewAI
Контекст: Сергій 2026-05-11: «зібрати скіли з аналізу рекламних кампаній Google, Meta, TikTok, GTM, GA4. Зібрати з них CrewAI. Запустити аналіз минулого місяця, сформувати тижневі та щоденні звіти.» Це research-фаза. Implementation план — окремий документ.
TL;DR
Будуємо 4-агентну CrewAI (MVP) поверх існуючої інфраструктури. Дані в основному вже є — BigQuery ad-analytics-hub.ad_data.* (Google Ads BQDTS, daily), Meta Marketing API (26 accounts), GA4 через Playwright. TikTok чекає OAuth handshake. GTM — поки нема pipeline.
Очікуваний обсяг роботи: 3-5 днів для MVP daily digest (4 ролі + 12 alert rules + Telegram звіт). Weekly review — окрема ітерація.
1. Базові скіли крос-канального ads analyzer'а (10 ключових)
- Data ingestion & normalization — pull з Google Ads MCC, Meta Marketing API, TikTok Business API, GA4 BQ Export → єдина схема (date, channel, campaign, spend, impressions, clicks, conv).
- Attribution literacy — розуміння різниць last-click (Google Ads) vs 7d-click/1d-view (Meta) vs data-driven (GA4); вміння reconcil'ити дельти.
- Anomaly detection (rule + ML) — статистичні правила («CPA +50% vs 7d avg») + baseline-aware ML для high-spend кампаній.
- Budget pacing — щоденний моніторинг spend velocity vs місячного плану, прогноз overshoot/undershoot.
- Search Query Mining — пошук негативів у Google Ads (high cost / 0 conv 14d), wasted spend → 20-40% економія.
- Creative fatigue detection — CTR/CPM drift в Meta, frequency cap, ad-level lifecycle.
- Bid strategy auditing — для Smart Bidding / PMax: optimization score, asset group performance, conversion signal hygiene.
- Audience overlap & saturation — Meta audience overlap tool, retargeting cannibalization.
- Conversion tracking QA — pixel/GTM/GA4 sanity checks, consent-mode breakage, view-through diffs.
- Narrative reporting — переклад цифр у insights + action items під PPC-команду (Юля/Катя/Андрій).
- Pharma compliance awareness — українські обмеження реклами ЛЗ (ст.21 ЗУ «Про рекламу»), interplay з legal-advisor agent.
- Cross-channel benchmark synthesis — порівняння Google vs Meta vs TikTok per SKU/бренд для re-allocation бюджету.
2. Запропоновані 5 ролей CrewAI агентів
| Роль |
Тип |
Responsibilities |
| Data Steward |
виконавець |
Daily pull з 4 джерел (Google Ads MCC через BQDTS, Meta MAPI, TikTok, GA4) → BQ ad-analytics-hub.ad_data.*, sanity checks, freshness alerts. Власник pipeline. |
| Channel Analyst (per-channel) |
ауд'ятор |
Глибокий аналіз 1 каналу: Google Ads (search/PMax), Meta (ASC/manual), TikTok. SQL поверх BQ + платформ-специфічні reasoning patterns. Рекомендую 1 агент з контекст-перемикачем для MVP. |
| Anomaly Watchdog |
ауд'ятор |
Прогон 12-15 alert rules (див. §4) → структуровані інциденти з severity, evidence, recommended action. Generates daily exception report. |
| Conversion Attribution Analyst |
ауд'ятор |
Reconcile Google Ads/Meta/GA4/tabletki.ua UTM. Знаходить tracking-breaks, дельти між кабінетами. Owner GA4+GTM-логіки. (v2 — коли GA4 BQ Export буде) |
| Strategy Synthesizer (Lead) |
стратег |
Зводить вихід усіх агентів → narrative daily digest + weekly review з action items, ранжує за impact. Це той самий «brain» що говорить з Сергієм + PPC. |
| (опц.) Budget Pacing Bot |
виконавець |
Окремо якщо буде багато брендів — щодня перевіряє spend vs план, ескалує overshoot ризик. |
MVP = 4 ролі (Data Steward + Channel Analyst + Anomaly Watchdog + Strategy Synthesizer). Attribution Analyst додати v2 коли GA4 BQ Export запрацює.
3. Daily KPI для фарма-реклами в Україні
Поверх стандартних (Spend, Imp, Clicks, CTR, CPC, Conv, CR, CPA, ROAS, Impr.Share):
- Sales on tabletki.ua per UTM source/medium — primary conversion (бо direct-to-consumer без власного e-com у більшості SKU).
- Cost per Tabletki sale (per-SKU) — фактичний eCPA з реальною монетизацією.
- Sales velocity per SKU (units/день) vs spend per SKU — for reallocation.
- Search Impression Share на brand keywords (Schönen, Vitabiotics, ProFLEX) — захист бренду.
- Non-brand vs brand spend split — щоб не «фарбувати» bottom-of-funnel результати органікою.
- PMax / ASC asset group health — optimization score, конверсії per asset group.
- GA4 engaged sessions per medizine.ua landing — proxy для якості трафіку коли немає прямого conv-сигналу.
- Frequency (Meta) — фарма-аудиторія швидко вигорає, hard cap ~4-5.
- % legal-compliant ads live — крос-чек з legal-advisor agent (особливо ЛЗ-SKU).
- Tracking health score — % кампаній з валідним conv-pixel за 24h.
4. Alert rules (12-15 правил для auto-flagging)
- Zero conv + spend >500 грн / 3 дні поспіль (per ad group) → pause candidate.
- CPA > 150% від 7d-avg (campaign-level, мін. 5 conv baseline) → red flag.
- CTR drop >50% week-over-week при impr >1000 → creative fatigue / disapproval.
- CPC spike >40% day-over-day → auction volatility або bid-strategy reset.
- Spend velocity overshoot — daily run-rate проектує >115% monthly budget.
- PMax optimization score <60% → audit recommendations needed.
- Meta frequency >5.0 на active ad set → audience saturation.
- Search query 0 conv / >300 грн / 14 днів → негатив-кандидат.
- Conv tracking drop >80% vs 7d baseline → pixel/GTM break (urgent).
- Impression share lost (rank) >40% на brand-кампанії → competitor incursion.
- Tabletki UTM mismatch — клік є в Google/Meta, але немає в Tabletki UTM-логах 48h.
- Disapproved ads >0 → миттєвий alert (особливо для ЛЗ-SKU + legal compliance).
- GA4 engagement rate <30% на paid landing → poor LP/audience fit.
- Spend concentration risk — 1 кампанія >40% денного бюджету бренду.
- Day-of-week anomaly — суботній/недільний spend без conv-trend support.
5. Daily report формат + Weekly review блоки
Daily digest (Telegram, ~10 хв читання)
- TL;DR — 3 рядки: загальний spend / conv / red flags count.
- Channel pulse — табличка Google/Meta/TikTok: spend, conv, CPA, day-vs-7d-avg delta.
- 🚨 Anomalies — топ-5 алертів за severity з recommended action.
- 💰 Wins — 2-3 best-performing units (для морального тонусу команди).
- 🎯 Action items для команди — конкретно «Юля: додати негативи в кампанію X», «Катя: оновити креативи set Y».
Weekly review (понеділок ранок, ~30 хв read)
- WoW summary per channel + per brand.
- Budget pacing vs місячний план.
- Creative performance review (top/bottom 3 ads per канал).
- Search query mining results (нові негативи).
- Cross-channel reallocation recommendations.
- PMax/ASC asset group deep-dive.
- Tabletki UTM funnel analysis.
- Tracking health report (GA4 + pixel + GTM).
- Open experiments status.
- Strategic recommendations на наступний тиждень.
6. GA4 + GTM поверх рекламних кабінетів
GA4/GTM додають:
- Cross-channel attribution — data-driven model, conversion paths, assisted conversions (рекл. кабінет бачить тільки свій канал).
- Reconciliation — реальна voronka post-click: bounce, scroll, engaged sessions per лендінг. Платформи звітять inflated conv (особливо Meta view-through).
- Audience signals — GA4 audiences з behavioral conditions → exporт у Google Ads/Meta для retargeting якісніших.
- De-duplication — Google + Meta sumарно часто >100% реальних conv; GA4 рахує 1 раз.
- GTM як центральний event hub — один dataLayer push fires Meta Pixel + GA4 + Google Ads conv-tag, узгоджені тригери. Уникає 3 окремих імплементацій з різними дефініціями event'у.
- Consent mode тестування — критично для UA-cookie banner на medizine.ua, тут GTM-аудит обов'язковий.
Для команди ця інтеграція = primary input Attribution Analyst-агента у v2 (коли GA4 BQ Export буде налаштовано замість поточного Playwright-екстрактора).
7. Наявні дані і прогалини (наша реальність)
| Канал |
Дані |
Стан |
Що бракує |
| Google Ads |
BQ ad-analytics-hub.ad_data.* (190 таблиць, daily) |
✅ Готово |
— |
| Meta Ads |
Marketing API через /srv/tools/meta-ads/, токен Вови |
🟢 Готово (API live), але немає BQ-export — pull on-demand |
Налаштувати ETL → BQ для historicals |
| TikTok Ads |
App approved 06.05, OAuth pending |
🟡 Pipeline ще немає |
OAuth handshake + extractor |
| GA4 (medizine.ua) |
Playwright + cookies Сергія |
🟡 Працює як rescue, не BQ Export |
Налаштувати GA4 BigQuery Export (нативний) |
| GTM |
— |
🔴 Не підключено |
Окремий sub-project, на старт |
| Tabletki sales+UTM |
BQ ad-analytics-hub.tabletki.* (weekly cron) |
✅ Готово |
— |
Висновок: для MVP достатньо Google Ads + Meta + Tabletki UTM. TikTok, GA4 BQ Export, GTM додаються у наступні ітерації.
8. Стек технологій (узгоджено з нашими інструментами)
- CrewAI Framework — як у case-builder-crew, dev-crew, google-ads-crew
- Gemini API через
/srv/passepartout/google/gemini-sandbox.key (AI Ultra) — як основний LLM
- BQ Python client через
ad-pipeline-worker-sa.json для SQL поверх BQDTS
- Meta Marketing API через
/srv/tools/meta-ads/ (vova-token-longlived)
- Pharma compliance — інтеграція з legal-advisor agent для disapproval checks
- Telegram bot для daily digest (через
/srv/passepartout/telegram/claude-bot.token)
- systemd timers для daily/weekly запуску (як scout-agent)
- Wiki integration — повний звіт пишеться у
/srv/wiki/projects/deltamedical/ad-analytics-hub/reports/YYYY-MM-DD-daily.md + Telegram summary
- AgentDB integration — semantic search по історичних звітах для контексту
9. Рекомендований план implementation (3-5 днів)
Day 1: Data Steward + SQL queries
- Створити
/srv/projects/ads-analyzer-team/ + venv
data_steward.py: 4 функції-pull (Google Ads через BQ, Meta через API, Tabletki UTM з BQ, заглушки для TikTok/GA4)- Уніфікована схема
daily_metrics.parquet або BQ-table ad-analytics-hub.analyzer.daily_unified
- Test: full pull за останні 30 днів
Day 2: Anomaly Watchdog + 12 правил
anomaly_watchdog.py з 12 правилами (див. §4)- Виведення в JSON:
{rule_id, severity, channel, brand, evidence, recommended_action}
- Test на історичних 30 днях — який сигнал у різні дні?
Day 3: Channel Analyst + Strategy Synthesizer
channel_analyst.py: глибокий per-channel reasoning через Gemini (3 prompts: Google / Meta / TikTok)strategy_synthesizer.py: zведення всіх трьох + anomalies → narrative digest- Test: daily digest на 5-10 травня (минулий тиждень) → перевіряємо якість
Day 4: CrewAI orchestration + Telegram
crew.py: послідовний flow 4 агентів (Data → Channel → Anomaly → Synthesizer)- Telegram-bot інтеграція: формат з §5
- systemd timer
ads-analyzer-daily.timer на 06:00 Kyiv = 03:00 UTC
- Self-test run
Day 5: Weekly review + tuning
weekly_review.py: окремий flow з 10 блоками (див. §5)- systemd timer
ads-analyzer-weekly.timer на понеділок 07:00 Kyiv = 04:00 UTC
- Doc у wiki
- Замінити старий
daily_analyzer.py (зараз disabled)
10. Open questions для Сергія
- Бюджет на місяць по брендах — для budget pacing alert (правило #5) потрібен план/cap. Де брати? CRM, Notion, окремий sheet?
- Brand ↔ кампанія mapping — у
account_descriptive_name бачимо «Bioxine», «Vitabiotics» тощо. Чи маємо канонічний реєстр SKU per бренд для cross-sell і per-SKU reporting? У products-каталозі є (309 SKU / 72 бренди), але треба cross-reference з рекламними account'ами.
- Daily digest для кого? — тільки Сергій або CC PPC-команді (Юля/Катя/Андрій) теж? Може окремий формат для команди (technical) vs Сергія (executive)?
- Weekly review час — понеділок 07:00 ОК або інший день?
- Action items routing — чи робимо integration з Notion для відстеження виконання alerts? Або тільки Telegram-нагадування?
- Legal-advisor integration — підключати на кожен новий disapproval alert чи batch раз на тиждень?
- GA4 priority — налаштувати GA4 BQ Export як окрему підзадачу до запуску ads-analyzer-team, або старт без GA4 і додати у v2?
11. Cross-references
12. Sources (websearch)