Meta Ads Toolkit

Оновлено: 2026-04-23 Стадія: Brief (працює MVP, документуємо) Власник: Digital team (Вова, Сергій)

Ідея

Програмний read-only доступ до Meta Marketing API через власну app Deltamedical — щоб команда могла швидко проганяти аудит кампаній, витягувати інсайти по плейсментах, порівнювати кабінети і автоматизувати репорти без платних конекторів типу Supermetrics.

Brief

Кому: Digital team (Вова Digital Lead, Сергій, Юля/Катя/Андрій PPC) Навіщо: замінити ручне копіпастання з Meta Ads UI + економія на Supermetrics ліцензії там де можна тягти напряму. Плюс — можна робити глибокий аналіз (placements, breakdowns, creative fatigue tracking) який UI ховає під зайвими клацаннями. Метрики успіху:

• Time-to-audit кампанії < 1 хвилини (через скрипт vs 15-30 хв руками)
• Автоматичні weekly-digest з ad accounts (ЩО ДАЛІ)
• Reports для PPC-команди по best-practices check (Audience Network, застарілі об'єктиви, creative fatigue)

Що вже працює (MVP)

• Власна Meta Business App delta-graph (App ID 1327888782563204), Live Mode
• User token (long-lived, 59 днів) у passepartout — /srv/passepartout/meta/vova-user-token-longlived-*.txt
• Marketing API — читаємо 26 ad accounts Deltamedical
• Helper-скрипти:
  • /srv/tools/meta-ads/audit.py <account_id> "<campaign_substring>" — повний аудит за 30 сек
  • /srv/tools/meta-ads/list-accounts.py — список доступних кабінетів
• Best-practice чек-листи у аудиті: Audience Network detection, LINK_CLICKS застарілість, campaign age, stop-date warnings

Перший реальний use-case (2026-04-23)

Аудит кампанії Perfectil | cpc | у WHC: виявив що 77% бюджету летить у Audience Network (фейкові кліки з ігор), об'єктив застарів, кампанія живе 2+ роки без рестарту. Звіт: /srv/research/2026-04-23/meta-ads-audit-perfectil-cpc-whc.md.

Технологічний стек

• API: Meta Graph API v19.0 (endpoints: /me/adaccounts, /act_X/campaigns, /act_X/insights, breakdowns)
• Auth: User token → exchange на long-lived (60 днів). TODO: System User token для постійного read-only доступу (не експайриться)
• Мова: Python 3 stdlib + curl (без зовнішніх залежностей)
• Зберігання: покрокове — зараз stdout, наступний крок BigQuery dump

TODO (roadmap)

• [ ] System User token (not-expiring) — Вова створить у BM DMAG KZ з role Employee + View Performance scope на ad accounts. Критично для автоматичних cron'ів.
• [ ] Identity Confirmation Вови (facebook.com/ID/confirm) — відкриє доступ до Ad Library API (/ads_archive) для парсингу реклами конкурентів
• [ ] Ad Library API скрипт (ads-library.py) — після identity
• [ ] BigQuery dump — daily dump insights у BQ dataset, щоб PPC-команда могла писати SQL і робити дашборди у Looker
• [ ] Weekly digest email — cron щотижня зі звітом по всіх active campaigns
• [ ] Оформити як skill /srv/wiki/skills/meta-ads-audit/ — щоб команда могла запускати через Claude desktop
• [ ] Pivot to OUTCOME_SALES check — аудит автоматично помічає кампанії з застарілим об'єктивом LINK_CLICKS і рекомендує перехід

Що НЕ робимо (out of scope)

• Запис/створення/редагування кампаній через API (read-only принцип)
• Авто-оптимізація (зараз рекомендаційна, не виконавча)
• Конкурентна розвідка без identity confirmation

Посилання

• Memory: /root/.claude/projects/-/memory/infra_meta_ads_toolkit.md
• Приклад аудиту: /reports/research/2026-04-23/meta-ads-audit-perfectil-cpc-whc.md
• Інструкція активації app: /reports/research/2026-04-23/meta-app-delta-graph-activation.md
• Handoff для web Claude (помогти Вові пройти активацію): /reports/research/2026-04-23/handoff-web-claude-meta-data-deletion.md

Ризики

• Токен Вови — персональний. Якщо Вова піде з компанії або зніме доступ — все ламається. Мітигація: System User token від імені організації.
• Meta API rate limits — 200 calls/hour на user token. Для нас достатньо, але при масштабуванні треба стежити.
• App Review ніколи не потрібен (читаємо тільки свої кабінети) — але якщо надумаємо SaaS-функціонал (давати доступ клієнтам), знадобиться.