---

type: project parent: ad-analytics-hub name: Google Ads integration slug: google-ads status: active readiness_pct: 80 last_updated: 2026-05-05

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

ETL Google Ads (MCC) → BigQuery → Notion daily report. Agency-level pipeline через MCC account access.

Meta

Why: агентський MCC покриває кілька клієнтів Deltamedical, центральне місце для daily KPI замість ручних Google Ads UI-перевірок.

Status:

• 🟢 MCC daily download стабільний з кінця квітня
• 🟢 Daily analyzer пише у Notion
• 🟢 google-ads-crew (5 AI-агентів через Gemini CLI) — окремий MVP для creative генерації, є тут як sub-shop

Implementation

Cron

Виконавчі скрипти живуть у /srv/projects/google-ads-crew/. Розклад і власники — у глобальному реєстрі крон у MEMORY.md.

BQ datasets

Канонічне джерело даних: ad-analytics-hub.ad_data.* — Google Ads native BigQuery Data Transfer Service (BQDTS) export.

• GCP проект: ad-analytics-hub (location: EU)
• Dataset: ad-analytics-hub.ad_data
• MCC Customer ID: 191-068-9182 → 1910689182 (без дефісів, суфікс у назвах таблиць)
• Кількість таблиць: 190 (станом на 2026-05-11): 100+ ads_* (поточні) + 90+ p_ads_* (історичні partition'и)
• Розклад: daily, ~01:27 UTC (latest modified time)
• Свіжість даних: _DATA_DATE лагає 2 дні (Google standard для conversion-aware reporting), тобто 2026-05-11 → latest_date=2026-05-09
• Service account для читання: /srv/passepartout/google/ad-pipeline-worker-sa.json (роль BigQuery Data Viewer + BigQuery User)
• Розмір: ТОП-5 таблиць (по 1+ GB): p_ads_AgeRange, p_ads_AdGroupCriterion, p_ads_Keyword, p_ads_Ad, p_ads_ClickStats

Топ-15 таблиць

1872.6 MB | 3.6M rows | p_ads_AgeRange_1910689182
1458.5 MB | 8.6M rows | p_ads_AdGroupCriterion_1910689182
1437.6 MB | 5.5M rows | p_ads_Keyword_1910689182
1403.4 MB | 2.1M rows | p_ads_Ad_1910689182
1049.0 MB | 3.1M rows | p_ads_ClickStats_1910689182
 883.9 MB | 3.1M rows | p_ads_AdGroupAdLabel_1910689182
 759.5 MB | 1.6M rows | p_ads_ParentalStatus_1910689182
 511.8 MB | 3.5M rows | p_ads_CampaignCriterion_1910689182
 489.7 MB | 1.3M rows | p_ads_GeoStats_1910689182
 402.1 MB | 853K rows | p_ads_SearchQueryStats_1910689182
 393.9 MB | 780K rows | p_ads_Gender_1910689182
 383.4 MB | 1.7M rows | p_ads_AdGroupBidModifier_1910689182
 279.4 MB | 790K rows | p_ads_HourlyAdGroupStats_1910689182
 201.4 MB | 496K rows | p_ads_KeywordStats_1910689182
 187.1 MB | 372K rows | p_ads_AdGroupAudience_1910689182

Типові таблиці і їхнє призначення

• ads_AccountBasicStats_<mcc_id> — daily KPI на рівні account (impressions, clicks, cost, conversions)
• ads_CampaignStats_<mcc_id> — campaign-level з усіма метриками
• ads_AdGroupStats_<mcc_id> — ad-group рівень
• ads_Keyword_<mcc_id> + ads_KeywordStats_<mcc_id> — keywords + статистика
• ads_SearchQueryStats_<mcc_id> — search query reports
• ads_AgeRange*, ads_Gender*, ads_ParentalStatus* — демографія
• ads_GeoStats_<mcc_id> — географія
• ads_HourlyAdGroupStats_<mcc_id> — погодинна аналітика
• ads_ClickStats_<mcc_id> — click-level (для conversion attribution)
• ads_AdGroupAudience_<mcc_id> + *Stats — audience-based reporting
• ads_*ConversionStats_<mcc_id> — conversions per dimensions
• ads_*CrossDeviceStats_<mcc_id> — cross-device atrybucja

Префікс p_ads_* — це Google's partition-зliating версія для бекфілу і повної історії. Префікс ads_* — поточна active table.

Як перевірити свіжість

from google.cloud import bigquery
import os
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/srv/passepartout/google/ad-pipeline-worker-sa.json"
client = bigquery.Client(project="ad-analytics-hub")
q = "SELECT MAX(_DATA_DATE) AS latest FROM `ad-analytics-hub.ad_data.ads_CampaignBasicStats_1910689182`"
print(next(client.query(q).result()).latest)
# Очікуване: today - 2 days

Як налаштовано BQDTS (для відновлення/migration)

Налаштовується через GCP Console (BQDTS API не дозволяє менеджмент з нашого SA через permissions):

1. GCP Console → BigQuery → Data Transfers
2. Create Transfer → Data source: «Google Ads (formerly AdWords)»
3. Destination dataset: ad_data
4. Customer ID: 191-068-9182 (наш MCC)
5. Refresh window: 7 days (standard)
6. Schedule: daily

Авторизація: робиться через GCP user-account який має Google Ads access (через Manager Account). Якщо потрібно перенаправити transfer — robi його під masterdigital@ (всі Google Ads under it).

Custom CSV pipeline (secondary, не критичний)

• Custom MCC CSV pipeline через Playwright cookies — fallback для UI-specific reports (screenshots, відхилені оголошення). Зараз cookies expired з 2026-04-16, але це secondary. Канонічний BQ pipeline (вище) працює незалежно.

Auth для secondary REST API запитів (policy endpoint)

• OAuth2 token у /srv/passepartout/google/google-ads.yaml
• developer_token + client_id/client_secret + refresh_token (читай /srv/passepartout/google/google-ads-readonly-savchenko.key.meta для деталей)
• Status: refresh_token expired з 2026-05-01 (app у Testing mode, 7-day TTL). Для відновлення — PUBLISH APP у GCP Console + re-OAuth.

Code

• /srv/projects/google-ads-crew/ — pipeline + AI-crew
• mcc_report_downloader.py — download
• daily_analyzer.py — Notion report
• audit_campaigns.py, landing_healthcheck.py, setup_google_ads_oauth.py — utility scripts

Backlog

• [ ] Доcумnet точний ENV google-ads.yaml шлях (потрібен Passepartout audit)
• [ ] OAuth handoff для Search Campaign Builder (#63 у задачах) — чекає Сергія
• [ ] BQ schema documentation (зараз pipeline пише без формального schema-doc)
• [ ] Telegram нотифікація на crash (зараз просто пише у /var/log)

Open questions

1. Чи потрібно витягати GA4 attribution прямо з Google Ads (через Connected Linked Accounts) чи окремо?
2. Чи інтегрувати Search Term Reports у BQ pipeline?