---

type: project parent: ad-analytics-hub name: Meta Ads integration slug: meta-ads status: active readiness_pct: 65 last_updated: 2026-05-05

Meta Ads integration (sub-project of Ad Analytics Hub)

Meta Marketing API live з 2026-04-23 через delta-graph app. Helper-скрипти для ad-hoc audit працюють. ETL у BQ — наступна фаза.

Meta

Why: Meta — другий за обсягом канал бюджетів Deltamedical (Facebook + Instagram), треба паралельно з Google Ads збирати кампаній / ad-set / ad / creative-level метрики у спільну BQ-шину.

Status (2026-05-05):

• 🟢 App delta-graph live (ID 1327888782563204), Marketing API + Facebook Login for Business approved
• 🟢 Long-lived user token Вови валідний (перевірено сьогодні: me/id=2209634536513419, name=Volodymyr Nik)
• 🟢 26 ad accounts доступні (з них 17 ACTIVE)
• 🟢 Helper-скрипти ad-hoc audit працюють (audit.py, list-accounts.py)
• 🟡 BQ dataset meta_ads.* ще НЕ створений — тільки ad-analytics-hub.ad_data зайнятий Google Ads BQ Transfer
• 🔴 Регулярний ETL у BQ — TBD
• 🔴 Cron-моніторинг — TBD
• ❌ Ad Library API — чекає identity confirmation Вови

Stakeholders:

• Power-user / app owner: Вова (Digital Lead, Volodymyr Nikolaychuk)
• Owner: Сергій
• ETL: VPS Claude

Implementation (current)

Auth (Passepartout)

• /srv/passepartout/meta/vova-ads-app.txt — App ID + App Secret (chmod 600)
• /srv/passepartout/meta/vova-user-token-longlived-2026-04-23.txt — long-lived user access token (~59 днів, треба refresh)
• /srv/passepartout/meta/andrii-savchenko-fb.txt — окрема auth (для tagged accounts)
• vova-ads-app.meta — опис, скоупи

Помічники (готові)

/srv/tools/meta-ads/:

• list-accounts.py — усі 26 кабінетів зі статусами
• audit.py <account_id> "<campaign_substring>" — повний audit кампанії за 30 секунд: metrics, ad sets, placements breakdown, best-practices check (Audience Network, застарілі об'єктиви, creative fatigue, stop dates). Формат — таблички з 🔴-маркерами.
• README.md — як кликати

Виклик з командою:

python3 /srv/tools/meta-ads/audit.py act_1909956542641924 "Perfectil"

Токен автоматично береться з ENV META_ACCESS_TOKEN → System User token → найсвіжіший short-lived.

Список 26 ad accounts (2026-04-23)

SH, CHC, WHC, PHC1/PHC2, Delta Medical (CY), Medizine, Deltaswiss AG/New, DM KZ/UZ, Humer, Bjola, BRauto, Opora ads, Schonen, Humanist, Up&Do World, … Повний — у /srv/tools/meta-ads/README.md.

App параметри

• App: delta-graph (ID 1327888782563204), namespace medizine.ua
• DPO: Volodymyr Nikolaychuk (Deltaswiss)
• Business Manager: DMAG KZ (ID 358625660399717)
• App Mode: Live ✓
• Products: Marketing API ✓, Facebook Login for Business ✓
• App Review: не потрібен (own ad accounts через BM)

Backlog

Phase 1 — ETL у BQ (наступний пріоритет)

• [ ] Створити BQ dataset ad-analytics-hub.meta_ads зі schema (campaigns, adsets, ads, creatives, daily metrics)
• [ ] Конвертувати audit.py логіку в ETL-режим: insights API → BQ (per account, daily)
• [ ] Cron на щоденне підтягування (синхронно з Google Ads MCC, наприклад 03:30 UTC)

Phase 2 — Token refresh + monitoring

• [ ] Token refresh механізм (long-lived expires ~60 днів) — або System User token (TODO попросити Вову зробити read-only System User з scope ads_read, View Performance)
• [ ] Telegram-алерт при наближенні expire або помилці API

Phase 3 — Ads Library

• [ ] Дочекатись identity confirmation Вови (facebook.com/ID/confirm) для Ad Library API access
• [ ] Інтеграція Ads Library у competitor-analysis sub-project (окремо від цього wiki)

Cross-references

• Memory (canonical): infra_meta_ads_toolkit.md
• Wiki integration: meta-ads-toolkit (помічники)
• Brand Threads sub-project (community/Threads-комунікація брендів) — окремий проект, не аналітика

Open questions

1. Чи робимо paid + organic insights разом, чи тільки paid?
2. Який business_id MAIN для зведеного звіту?
3. Чи витягуємо Ads Library дані сюди (для competitor analysis), чи це окремий sub-project?
4. Yevgeniy Sokhan (act_497104840400249) — чий це кабінет, чому з'являється у списку?

Приклади аудитів

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