name: competitor-ad-research description: Зібрати рекламні креативи конкурента з Google Ads Transparency Center і згенерувати маркетинговий звіт з аналізом angles/hooks/funnel. Використовуй коли треба швидко подивитись що крутить конкурент (бренд/ринок), розрізати сторінку Transparency Center на окремі креативи, зробити review всіх оголошень і видати лінк на markdown-звіт. Приклад запиту: "подивись що крутить Perla Helsa в UA по колагену", "збери всі банери Zest в Google Ads", "що в рекламі Humer зараз".

Competitor Ad Research — 2-stage pipeline

Автоматичне дослідження реклами конкурента на Google Ads Transparency Center. Вихід — звіт з кропами + маркетинговим аналізом кожного креативу.

Коли використовувати

Бриф на нову кампанію → треба knowledge про що роблять конкуренти
Бенчмарк креативів (angles, hooks, CTA, funnel-position)
Моніторинг активного комунікаційного поля бренду/категорії
Поставили задачу "подивись що крутить X" → зразу цей pipeline

Архітектура

Stage 1 (Collector)                   Stage 2 (Analyzer)
┌──────────────────────────┐         ┌──────────────────────────┐
│ Gemini 2.5 Computer Use  │  PNGs   │ Gemini 2.5 Pro Vision    │
│ (browser agent)          │ ──────► │ (structured JSON)        │
│                          │         │                          │
│ • Playwright Chromium    │         │ • Per-screenshot analysis│
│ • Navigates Transparency │         │ • Bbox → PIL crop        │
│ • Screenshots за кроками │         │ • Dedup by headline      │
│ • History truncation     │         │ • Markdown report        │
└──────────────────────────┘         └──────────────────────────┘
      ↓                                     ↓
 /tmp/cu-poc/<brand>/step-*.png        /srv/reports/assets/<slug>/
                                       /srv/reports/<slug>.md
                                       → http://31.131.26.203/reports/<slug>.md

Файли скіла

collector.py — Stage 1: browser-агент, збирає PNG
analyzer.py — Stage 2: Gemini Pro Vision, кропи + звіт
references/ — еталонні приклади, pricing, prompt recipes

Як запускати

Швидкий приклад (Perla Helsa UA, колаген)

# Stage 1 — browser agent збирає скріни
cd /tmp && python3 /srv/wiki/skills/competitor-ad-research/collector.py
# → /tmp/cu-poc/perla/step-*.png (1–20 кроків залежно від складності)

# Stage 2 — аналіз + звіт
python3 /srv/wiki/skills/competitor-ad-research/analyzer.py \
  --input-dir /tmp/cu-poc/perla \
  --brand "Perla Helsa" \
  --region "Україна" \
  --output-dir /srv/reports/assets/perla-helsa-2026-04-22 \
  --report-path /srv/reports/perla-helsa-creative-review-2026-04-22.md
# → http://31.131.26.203/reports/perla-helsa-creative-review-2026-04-22.md

Адаптація collector.py під іншого рекламодавця

У collector.py є рядок task = "...". Треба:

Замінити назву бренду (і латиницею, і кирилицею)
Уточнити регіон (?region=UA у стартовому URL)
Задати тематичний фільтр (колаген / магній / тощо), якщо треба
OUTDIR = Path("/tmp/cu-poc/<brand-slug>")

Все інше (truncation, screenshot loop, safety acknowledgement) універсальне.

Вартість одного звіту

Вимірювання по Perla Helsa (UA, колаген, 13 скрінів → 22 унікальні креативи):

Stage	Модель	Input tok	Output tok	Cost
1. Collector	`gemini-2.5-computer-use-preview`	115 027	3 651	$0.18
2. Analyzer	`gemini-2.5-pro` (vision + JSON)	~REFILL~	~REFILL~	$REFILL
Total				$REFILL

Stage 1 основна стаття витрат — браузерні скріни великі, мультимодальний input товстий. Оптимізація: truncate_history(keep=4 turns) зрізає input токени в ~4× vs keep-all.

Якщо регіон не віддає результатів за 20 кроків (ліміт MAX_STEPS) — collector завершується і Stage 2 пропускається.

Prompt Stage 2 (analyzer)

Ключова частина — structured JSON output з фіксованим списком полів:

id, bbox_norm, format, topic, headline, body_text, url_shown,
visual_description, angle, hook, cta, promo, funnel_position, marketing_review

angle і funnel_position — закриті enum'и, щоб потім можна було робити meta-зрізи (таблиця "angle × кількість креативів").

Що дає на виході

creatives.json — сирий масив з повним аналізом (machine-readable)
crops/*.png — однорідні вирізки кожного креативу (PIL crop по bbox)
report.md — формат на кожен креатив:
- Картинка-кроп
- Formatfact-sheet (формат, тема, funnel, angle, URL)
- Текст + візуал
- Hook + CTA + промо
- Маркетинговий review (2-3 речення)
- Meta-таблиці angles і funnel position знизу

Типові підводні камені

Консент-діалоги Google — collector навчений їх клацати, але інколи локаль-залежне.
Safety decisions — CU Preview може просити підтвердження кліка; обробляється через safety_acknowledgement: "true" у function response.
Дублі креативів — analyzer робить dedup по (headline[:50], format). Може бути hover-версія одного ж банера — ручна перевірка корисна.
Обрізані картки — system prompt їх ігнорує, але інколи пропускає напів-обрізані.

Розширення (TODO / ідеї)

Підтримка Meta Ad Library (той же pipeline, інший Stage 1)
Cross-brand compare: 2 конкуренти → звіт з відмінностями
Trendwatch: щотижня перезапускати на list брендів → diff з минулим запуском

Пов'язане

/srv/wiki/skills/ppc-ad-copy/SKILL.md — коли треба написати власні оголошення на основі дослідження
/srv/reports/ — всі згенеровані звіти, доступні за лінком через Reports Hub