Dokumentacja publiczna

Co dokładnie dostajesz
w pakiecie Space Ads OS

Pełna lista komend, agentów, raportów i specyfikacji kreacji. To podgląd — komplet dokumentacji (pliki markdown: komendy, agenci, baza wiedzy) instaluje się razem z pakietem i jest czytelny wprost w Claude Code.

Aktywuj subskrypcjęWróć do strony produktu
Historia wersji systemu (changelog) →

Kanały

Co czyta i co zmienia

Cztery kanały, dwa modele auth. Google Ads — Twój developer token z Twojego MCC (zwykłe konto Google Ads nie wystarczy, trzeba mieć Manager Account; setup ~10 min). Pozostałe kanały — OAuth przez nasz bridge, zero ręcznej konfiguracji.

KanałReadMutateAuthAPI
Google AdstaktakTwój developer token z MCC + Twój OAuth clientv24.1
Meta AdstaktakOAuth przez oauth.spaceads.agency (tokeny szyfrowane lokalnie)Marketing API v25.0
TikTok AdstaktakOAuth przez oauth.spaceads.agency (auto-refresh)Business API v1.3
GA4takn/aOAuth lub Twój service account JSONData API

Google Ads

Pełny zestaw narzędzi pod aktualne API v24.1

17+ skryptów mutacji + diagnostyka, atrybucja, monitoring multi-account dla Google Ads API v24.1. Każdy z konkretnym celem, każdy do uruchomienia jedną komendą. Wsparcie v24.1: iOS vs Android (segments.mobile_device_platform), frequency-of-reach (unique_users_*_plus), eksperymenty z bezpośrednimi statystykami (point estimate, MoE, p-value) i bramkowane mutacje PMAX_REPLACEMENT_SHOPPING.

  • Audyt 360° konta

    19 sekcji diagnostyki w jednym przebiegu: struktura kampanii, słowa kluczowe, tracking, quality score, ustawienia konta, alerty learning phase. Wynik z health score 0–100.

    google_ads.scripts.full_audit

  • Search terms i bezpieczne negatywy

    N-gram analysis (1/2/3 słów) wykrywa wzorce zmarnowanego budżetu na poziomie statystyki, nie pojedynczych zapytań. Sugeruje negatywy w PHRASE i EXACT — BROAD match jest hardkodowo zablokowany.

    google_ads.scripts.search_terms_analyzer

  • Shopping + Merchant Center

    Product-level ROAS z podziałem Stars / Workers / Zombies / Draggers. Diagnostyka feedu (błędy, brakujące pola, policy violations) przez Merchant Center Content API v2.1.

    google_ads.scripts.feed_optimizer + google_ads.merchant_center

  • Performance Max — pełen wgląd

    Breakdown SEARCH / CONTENT / YOUTUBE / DISCOVERY per asset group. Wykluczenia gender (v24), retail filter shared sets (v24), VTC toggle. iOS vs Android per kampania (v24.1, segments.mobile_device_platform). To, czego sam panel nie pokazuje.

    google_ads.scripts.pmax_channel_performance + device_performance

  • Tworzenie kampanii PMax od zera

    Nie tylko analiza — system buduje całą kampanię Performance Max: budżet, kampanię (PAUSED, Maximize Conversion Value z docelowym ROAS) i osobną grupę zasobów per tier z filtrem produktowym po item_id. To silnik /spaceads-bucketing: od segmentacji feedu (Platinum/Gold/Silver/Bronze) do gotowej struktury, w całości pod 6 warstwami ochrony i domyślnie w trybie podglądu.

    google_ads.mutations.create_pmax_campaign + create_asset_group_with_listing_filter

  • Cart data — co kupują, co dokładają

    Nowy widok z Google Ads v24: lead_revenue (produkt, który przyciągnął klik) vs cross_sell_revenue (co dosypał do koszyka). Kluczowe dla e-commerce z szerokim asortymentem.

    google_ads.scripts.cart_data_analysis

  • Bidding (tROAS / tCPA) z guardrails

    Zmiana target ROAS w zakresie 0,5×–20×, max ±30% per zmiana. Preview pokazuje historię ROAS kampanii, system blokuje skoki, które wybiją learning phase.

    google_ads.scripts.update_troas

  • Geo, device, daypart

    Wydajność per kraj (z indeksem koncentracji HHI), per urządzenie, per godzina dnia. Identyfikuje wasted spend po regionach i porach, sugeruje wykluczenia geo.

    google_ads.scripts.geo_analysis + google_ads.scripts.device_performance

  • Attribution gap GA4

    Konfrontuje kliknięcia z Google Ads z sesjami w GA4. Pokazuje, gdzie ścieżka konwersji się rozjeżdża (utracone parametry UTM, problemy z tagiem, multi-domain). Plus landing page health: bounce, engagement, czas sesji per kampania.

    google_ads.ga4_helper + google_ads.scripts.landing_page_check

  • Monitoring i alerty

    Daily alert check pod całym MCC: learning limited, budget pacing off, drastyczna zmiana ROAS, brak spendu, suspension risk. Email digest, JSONL audit trail, opcjonalnie integracja przez webhook.

    google_ads.scripts.alert_check + google_ads.scripts.campaign_watchdog

  • Frequency-of-reach (v24.1)

    Nowy widok z Google Ads v24.1: unique_users_two_plus … ten_plus na poziomie konta. Pokazuje, ilu unikalnych użytkowników widziało reklamę 2×, 3×, 5×, 10×. Diagnostyka flaguje thin frequency (<30% widzi 2×), sweet-spot (avg 3–5, 5+ udział 40–65%) i saturation (≥20% widzi 10×). Domyka warstwę reach × frequency w raporcie brand awareness.

    google_ads.scripts.frequency_reach

  • Eksperymenty: bezpośrednie statystyki + bramkowane shippowanie (v24.1)

    PMAX_REPLACEMENT_SHOPPING + 6 pozostałych nowych typów eksperymentów z v24.1. Skrypt experiment_stats czyta point estimate, margin of error i p-value dla 7 metryk (ROAS change, conversions, cost, CPA, …) prosto z API. Bramkowane mutacje end_experiment (rollback) i graduate_experiment (ship) blokują się przed wywołaniem API, jeśli któryś z trzech progów nie przechodzi: ≥14 dni runtime, ROAS p ≤ 0.05, uplift ≥ +5%.

    google_ads.experiments + scripts.experiment_stats + mutations.graduate_experiment

Meta Ads

Diagnostyka, optymalizacja i bezpieczne zmiany dla Facebook + Instagram

5 skryptów mutacji + diagnostyka, recommendation engine i blended GA4 dla Marketing API v25.0. Czytasz, optymalizujesz i wykonujesz zmiany w jednym miejscu — z mandatory confirm wrapper, który nie pozwoli wykonać niczego bez Twojej akceptacji.

  • Insights z trzech poziomów

    Campaign / AdSet / Ad — wszystko dostępne w jednym przebiegu. Akcje ekstrahowane z tablicy actions[], policzone CPA/ROAS/CTR z dokładnością do typu konwersji (Purchase, Lead, custom).

    insights.py + analysis.py

  • Diagnostyka i alerty

    Reguły progowe na frequency cap, CPA, CTR, ROAS — z poziomami CRITICAL / WARNING / INFO. Wykrywa kampanie w stagnacji learning, frequency ≥2.5× (warning) i ≥4× (critical), drift ROAS poniżej targetu.

    diagnostics.py

  • Recommendation engine

    Realokacja budżetu między adsets na podstawie mediany ROAS, sugestie tuningu frequency, identyfikacja audiences do testu. Każda rekomendacja z liczbami i uzasadnieniem.

    optimization.py

  • Blended Meta + GA4

    Łączenie insights Meta z GA4 po nazwie kampanii. Pokazuje, ile konwersji Meta liczy "u siebie", a ile GA4 widzi naprawdę po stronie sklepu — czyli prawdziwy attribution gap, nie spór o pixela.

    blended.py

  • Bezpieczne zmiany kampanii

    Pause / update budget / update ROAS target — z mandatory .confirm() wrapper. Nigdy delete (operacja zablokowana). Limity: budżet max ±30% per zmiana, odstęp 3–5 dni między tuningami.

    campaigns.py + adsets.py + safety.py

  • Trendy WoW / MoM i anomalie

    Tygodniowe i miesięczne porównania ze statystycznym wykrywaniem anomalii. Wskazuje, czy spadek to sezon, weekend, czy faktyczny problem z kampanią.

    trends.py

TikTok Ads

Pełna integracja z TikTok Business API v1.3

4 skrypty mutacji + diagnostyka kreacji, Smart+ migration i CAPI z EMQ dla TikTok Business API v1.3. Mutacje przez ten sam wzorzec dry-run + .confirm() co w Meta.

  • Insights na 4 poziomach

    Advertiser / Campaign / AdGroup / Ad — plus breakdown godzinowy. Domyślnie 26 metryk: spend, conversions, total_purchase_value, video_watched_2s, video_views_p100, ROAS, CPA, CTR. Wszystko z jednego endpointu /report/integrated/get/.

    insights.py + analysis.py

  • Diagnostyka kreacji TikToka

    Metryki, które TikTok faktycznie nagradza: hook rate (próg 30%), completion rate (próg 10%), frequency fatigue (warning 2.5×, critical 3.5×), creative decay po 10 dniach. Alerty z severity CRITICAL / WARNING / INFO.

    diagnostics.py + rules.py

  • Smart+ migration według reguł

    Sprawdza, czy kampania spełnia warunki Smart+: min. 50 konwersji/tydzień, EMQ ≥ 6 dla Pixela, 6+ wariantów kreacji, ROAS w przedziale ±15%. Jeśli tak — przygotowuje migration plan; jeśli nie — wskazuje, czego brakuje.

    optimization.py

  • Pixel + Events API (CAPI)

    Pełna obsługa server-side: POST /event/track/ z hashowaniem SHA-256 dla email/phone/external_id, dedup window 5 min, walidacja Event Match Quality (cel ≥ 6, ostrzeżenie poniżej 5). Smart+ i VBO wymagają Pixel + CAPI razem.

    pixel.py

  • Bezpieczne mutacje + bulk

    pause / resume / update_budget / update_bid — każda przez PendingAction z dry_run domyślnie. Limity: budżet ±30%, bid ±25%, min. 3 dni między zmianami w learning, blokada delete. Dla wielu kampanii naraz: bulk_pause_campaigns().

    campaigns.py + adgroups.py + safety.py

  • Async reports + GA4 blended

    Raporty powyżej 180 dni / 10k wierszy idą przez async flow (create → poll → download). Plus blended.py: merge insights TikToka z GA4 po nazwie kampanii — prawdziwy attribution gap między „TikTok mówi" a „GA4 widzi".

    reports_async.py + blended.py

GA4 + multichannel attribution

Jedna prawda po stronie sklepu, nie trzy spory o pixela

GA4 czyta read-only — system łączy go z Google Ads, Meta i TikTokiem po nazwie kampanii i pokazuje, kto naprawdę przyniósł konwersje.

  • Attribution gap GA4 vs panele

    Pokazuje różnicę między tym, co Meta liczy „u siebie", a co GA4 widzi w Twoim sklepie. Pixel argument zamknięty liczbami.

    multichannel.attribution_compare

  • Landing page health

    Bounce, engagement rate, czas sesji per kampania. Wyłapuje LP, które ciągną CPA w górę bez Twojej wiedzy.

    ga4.scripts.landing_page_quality

  • Cross-channel blended view

    Google + Meta + TikTok + GA4 w jednym CSV/HTML — wreszcie ujednolicona atrybucja w raporcie tygodniowym.

    multichannel.attribution_compare + multichannel.overview

23 slash commands

Pełna lista komend

Każda komenda z jednolinijkowym opisem i przykładem wywołania.

  • /spaceads-check

    Audyt 360° wybranego konta — 19 sekcji diagnostyki, health score 0–100, lista quick wins.

    /spaceads-check google_ads --period=last_30d
  • /spaceads-overview

    Stan wszystkich kanałów aktywnego klienta na jednym ekranie.

    /spaceads-overview --period=last_7d
  • /spaceads-monitor

    Daily alert check: learning limited, budget pacing off, drift ROAS, brak spendu, suspension risk.

    /spaceads-monitor --severity=warning
  • /spaceads-changes

    Audyt mutacji w ostatnich N dniach (z plików JSONL audit log per kanał).

    /spaceads-changes --days=14
  • /spaceads-strategy

    Plan optymalizacji na 30 dni z priorytetami i KPI, zakotwiczony w briefie klienta.

    /spaceads-strategy meta --goal=roas
  • /spaceads-keyword-research

    N-gram + intent analysis na search terms, propozycje negatywów PHRASE/EXACT.

    /spaceads-keyword-research --topic="winter jackets"
  • /spaceads-geo

    Performance per region (HHI), wykluczenia geo, koncentracja spendu.

    /spaceads-geo google_ads --period=last_90d
  • /spaceads-modify

    Zmiana z preview, mutation-reviewerem (APPROVE/WARN/BLOCK) i confirmem.

    /spaceads-modify "raise tROAS to 4.0 on Search Brand"
  • /spaceads-create

    Nowa kampania / ad set / negative list z playbooka branżowego.

    /spaceads-create campaign --vertical=dtc-ecommerce
  • /spaceads-report

    Raport HTML w branding klienta — wybierasz z 13 szablonów.

    /spaceads-report 02_ecommerce_performance --period=last_30d
  • /spaceads-ga4

    Attribution gap GA4 vs panele, landing page health, custom definitions audit.

    /spaceads-ga4 attribution --window=30d
  • /spaceads-whitelabel

    White-label branding raportów — logo, nazwa, paleta i stopka operatora lub per-klient.

    /spaceads-whitelabel set --logo=logo.svg --name="Twoja Agencja"
  • /spaceads-brand

    Wyciąga logo, paletę, fonty i głos ze strony klienta, zapisuje do brief.yaml.brand_system.

    /spaceads-brand extract --url=https://klient.pl
  • /spaceads-brief

    Generuje brief kreatywny pod cel kampanii — hook angles, value props, proof points, CTA.

    /spaceads-brief --campaign="Wiosna 2026" --objective=conversions
  • /spaceads-creative

    Wireframe per format z safety zones + walidator gotowych assetów.

    /spaceads-creative brief --platform=meta_stories
  • /spaceads-grow

    90-dniowy review strategiczny — 4-fazowy Socratic (7 osi), ranked backlog hipotez, roadmap 3/6/12 mc.

    /spaceads-grow --slug=acme-apparel
  • /spaceads-bucketing

    PMax: podział feedu na 4 tier (Platinum/Gold/Silver/Bronze) z osobnym budżetem i tROAS per tier.

    /spaceads-bucketing --customer-id=1234567890
  • /spaceads-seasonal

    Luki sezonowe — kategoria w peak (sandały latem, kurtki zimą), a Ty jej nie promujesz.

    /spaceads-seasonal --client-slug=acme
  • /spaceads-cadence

    Co zaległe / due / planowane na dziś — wszystkie taski review per klient i per CID.

    /spaceads-cadence overdue
  • /spaceads-intel

    Tygodniowy digest branżowy — Reddit (PPC/GoogleAds), 10 top blogów PPC, Google Ads Developer Blog.

    /spaceads-intel --since=7d
  • /spaceads-onboard

    5-minutowy setup rozmową — operator profile + pierwszy klient brief.

    /spaceads-onboard --add-client
  • /spaceads-client

    list / switch / add — zarządzanie wieloma klientami w jednym CLI.

    /spaceads-client switch acme-saas
  • /spaceads-agency

    Cross-client rollup spendu, ROAS i alertów do tygodniówki agencyjnej.

    /spaceads-agency rollup --period=last_7d

5 agentów AI

Wyspecjalizowani agenci Claude

Każdy z osobnym kontekstem — main Claude orkiestruje, agenci wykonują.

  • mutation-reviewer

    Niezależny review każdej mutacji przed Twoim "TAK"

    Inputy
    Plan zmiany, brief.yaml, historia kampanii, learning-phase status
    Outputy
    APPROVE / WARN / BLOCK + uzasadnienie + rekomendacja
    Model
    Claude Sonnet
  • report-builder

    Generuje raporty HTML w branding klienta

    Inputy
    Wybrany template, period, dane z kanałów, brand_system z briefu
    Outputy
    HTML responsywny, email-ready, otwiera się w przeglądarce
    Model
    Claude Sonnet
  • brand-extractor

    Wyciąga brand system ze strony klienta

    Inputy
    URL strony klienta
    Outputy
    logo, paleta, fonty, voice samples, confidence score 0.0–1.0
    Model
    Claude Sonnet
  • creative-director

    Brief + wireframe + walidacja safety zones per platforma

    Inputy
    Cel kampanii, brand_system, ad_style, format/aspect ratio
    Outputy
    markdown brief + HTML wireframe z safety overlay + walidacja assetu
    Model
    Claude Sonnet
  • onboarding-coach

    5-minutowy onboarding rozmową — operator + pierwszy klient

    Inputy
    Brak (uruchamiany SessionStart hookiem)
    Outputy
    .spaceads/operator.yaml + clients/<slug>/brief.yaml
    Model
    Claude Sonnet

13 szablonów raportów

Każdy szablon ma swoją publiczność

Generujesz komendą /spaceads-report <nazwa> --period=<okres>.

  • 01_executive_summary
    Dla kogo:
    Decision maker, klient C-level
    Główne sekcje:
    KPI cards, blended ROAS, channel split, top 3 rekomendacje
    Długość:
    2 ekrany, 3 min czytania
  • 02_ecommerce_performance
    Dla kogo:
    Performance manager sklepu DTC
    Główne sekcje:
    ROAS per kanał, top SKU, RFM, day-N retention, attribution gap GA4
    Długość:
    5 ekranów, 8 min czytania
  • 03_leadgen_performance
    Dla kogo:
    B2B / lead gen manager
    Główne sekcje:
    CPL, MQL→SQL pipeline, source quality scoring, time-to-MQL, CAC/LTV
    Długość:
    4 ekrany, 6 min czytania
  • 04_brand_awareness
    Dla kogo:
    Brand manager, kampanie TOFU
    Główne sekcje:
    Reach × frequency, brand search lift, share of voice, view-through
    Długość:
    3 ekrany, 5 min czytania
  • 05_social_engagement
    Dla kogo:
    Social media manager (TikTok/Instagram-first)
    Główne sekcje:
    Hook rate, completion rate, top posty, time-of-day heatmap, sentiment
    Długość:
    4 ekrany, 6 min czytania
  • 06_content_analysis
    Dla kogo:
    Creative team, content strategist
    Główne sekcje:
    Performance per format, n-gram tables, hook patterns, sentiment
    Długość:
    4 ekrany, 7 min czytania
  • 07_local_business
    Dla kogo:
    Multi-location, franczyzy
    Główne sekcje:
    League per lokalizacja, geo grid, calls heatmap, ratings, store visits
    Długość:
    5 ekranów, 8 min czytania
  • 08_growth_roadmap
    Dla kogo:
    Klient strategiczny + zespół wewnętrzny
    Główne sekcje:
    Snapshot KPI (30d/prev/YoY), 7-osiowa siatka decyzji, ranked backlog hipotez, 12-tyg Gantt, milestones 6/12 mc
    Długość:
    6 ekranów, 10 min czytania
  • 09_bucketing_proposal
    Dla kogo:
    Klient e-commerce przed launchem 4-tier PMax
    Główne sekcje:
    Tier cards Platinum/Gold/Silver/Bronze, treemap dystrybucji produktów, donut budżetu, 6-krok migration, ryzyka + rollback
    Długość:
    5 ekranów, 7 min czytania
  • 10_experiment_verdict
    Dla kogo:
    Klient po pilocie PMAX_REPLACEMENT_SHOPPING (v24.1)
    Główne sekcje:
    Verdict badge SHIP/HOLD/ROLL BACK, 95% CI bars per metryka, tabela p-value, gate checklist (≥14d, p ≤ 0.05, uplift ≥ +5%), trend ROAS challenger vs incumbent, gotowy fragment graduate_experiment()
    Długość:
    4 ekrany, 6 min czytania
  • 11_competitive_landscape
    Dla kogo:
    Klient zainteresowany pozycją wobec konkurencji
    Główne sekcje:
    Trend SOV 12 tyg., matryca konkurentów (imp share, overlap, position-above, top-of-page, outranking), bid posture per cluster, rekomendowane ruchy
    Długość:
    4 ekrany, 6 min czytania
  • 12_feed_health
    Dla kogo:
    E-commerce z dużym asortymentem / agencyjny audyt feedu
    Główne sekcje:
    Macierz halo-effect STAR/MAGNET/DRIVER/NICHE (v24 cart_data_sales_view), tablica Stars/Workers/Zombies/Draggers, disapprovals breakdown, completion pól, top Magnet SKU do Platinum
    Długość:
    5 ekranów, 7 min czytania
  • 13_seasonal_calendar
    Dla kogo:
    Klient sezonowy / e-commerce z kalendarzem kategorii
    Główne sekcje:
    Heatmap kategoria × tydzień na 90 dni (peak / shoulder / running / gap-peak / gap-shoulder), karty priority gaps z revenue-at-risk + asset SLA, shoulder gaps, donut coverage, asset prep timeline
    Długość:
    4 ekrany, 6 min czytania

Specyfikacje kreacji

Safety zones per platforma

Walidator sprawdza wymiary, safe-zone, contrast i text-on-image % przed uploadem.

PlatformaFormatWymiarySafe zone
MetaStories / Reels1080×1920 (9:16)top 250px, bottom 350px, side 60px
MetaFeed 1:11080×1080text-on-image ≤ 20% (rekomendacja)
Google Display5 aspect ratios1:1 / 4:5 / 1.91:1 / 9:16 / 16:9logo + headline w centralnych 80% ramki
TikTokIn-feed 9:161080×1920top 130px (handle), bottom 484px (CTA + caption)
LinkedInplaceholder—pełna spec po uruchomieniu kanału

Pełne specyfikacje w pakiecie: src/spaceads_os/knowledge/creative_specs/{meta,google_ads,tiktok,linkedin}.md.

Brand + creative pipeline

Od strony klienta do gotowej specyfikacji kreacji

Cztery kroki, każdy z własnym agentem lub komendą. Bez „wyślij mi PDF z księgą znaku" i bez 24h bana po review.

  1. 01

    Brand extract

    Agent brand-extractor pobiera logo, paletę, fonty i głos z URL klienta i zapisuje do brief.yaml.brand_system. Bez ręcznego briefingu.

  2. 02

    Brief

    /spaceads-brief generuje brief kreatywny pod cel kampanii — hook angles, value props, proof points, CTA — w głosie marki, nie w korpomowie.

  3. 03

    Wireframe

    Agent creative-director składa wireframe per format (Meta Story 1080×1920, Reel, Feed 1:1, Google Display 5 ratios, TikTok in-feed 9:16) z bezpiecznymi strefami i miejscami na text overlay.

  4. 04

    Validator

    Sprawdza, czy wymiary, safe-zone, contrast i text-on-image % są zgodne z polityką platformy. Co nie przejdzie review — wraca do iteracji od razu, nie po 24h banie.

6-warstwowy safety

Każda mutacja przechodzi przez sześć warstw

Pięć deterministycznych + jedna AI review (mutation-reviewer). Działa tak samo w piątek o 17 i niedzielę o 3.

  1. 01

    Input validation

    Typy, zakresy, scope konta — zanim cokolwiek dotknie API. Każdy script `*.mutations.*` ma własny schemat pydantic, który walidacja musi przejść jako pierwsza.

  2. 02

    LIMITS check

    safety.LIMITS per kanał: budżet ±30%, target ROAS ±30% (Google/Meta), bid ±25% (TikTok), max 200 negatywów per batch. Hard-blocked: REMOVE. Każdy LIMIT jest stałą w kodzie, nie configiem.

  3. 03

    Preview

    Human-readable diff: jaki obiekt, jakie pole, before → after, szacowany wpływ na spend. Wyświetlany w terminalu przed jakimkolwiek wywołaniem API.

  4. 04

    mutation-reviewer agent

    Subagent Claude Sonnet czyta plan w kontekście historii kampanii i playbooka, zwraca APPROVE / WARN / BLOCK. WARN podświetla ryzyko, BLOCK fizycznie blokuje. Działa przed Twoim "TAK", nie zamiast niego.

  5. 05

    Post-mutation verification

    Po wykonaniu zmiany system robi read-back z API. Jeżeli wartość po nie zgadza się z oczekiwaną, status "incomplete" + alert.

  6. 06

    Audit log (JSONL)

    Każda mutacja → logs/<channel>_changes.jsonl. Append-only. Pełen audit trail per klient.

Każda mutacja loguje się jako JSONL row z polami: timestamp, actor, account, object_type, object_id, field, before, after, reason, reviewer_verdict. Audit log = pełen rollback w jednej komendzie.

Tryb agencyjny

Wielu klientów, jedno CLI, izolowane audit logi

Każdy klient ma własny brief.yaml, własny voice.md, własny logs/changes.jsonl. /spaceads-agency dorzuca rollup cross-client — bez mieszania danych.

  • clients/registry.yaml — jedno źródło prawdy o aktywnych klientach
  • Per-klient brief.yaml: cele, ICP, voice, brand_system, vertical playbook
  • Per-klient credentials/ — Twój Google Ads token, Meta business, TikTok account są od siebie odseparowane
  • Per-klient logs/changes.jsonl — pełen audit trail dla każdego klienta osobno (RODO-friendly)
  • /spaceads-agency — cross-client rollup spendu, ROAS, alertów, do tygodniówki agencyjnej
clients/registry.yaml
clients:
  - id: acme-store
    name: Acme Store
    vertical: dtc-ecommerce
    channels: [google, meta, ga4]
  - id: acme-saas
    name: Acme SaaS
    vertical: b2b-saas
    channels: [google, meta]

Playbooki branżowe

Pięć branż, pięć różnych zestawów reguł

System wybiera wzorce optymalizacji pod Twoją branżę — tROAS targets, conversion lag, bidding strategy presety, struktura kampanii.

  • DTC e-commerce

    PMax + Shopping + Search brand. Stars/Workers/Zombies/Draggers segmentation. Cross-sell tracking. Conversion lag 3–7 dni.

  • Lead generation B2C

    Conversion ladder MQL→SQL, source quality scoring, lead value per stage. Conversion lag 7–14 dni.

  • B2B / SaaS

    Long sales cycle (14–30+ dni), MQL→SQL→Opportunity tracking, brand search incrementality, LinkedIn jako placeholder.

  • Mobile app

    Install→engage→retain funnel, AppsFlyer/Adjust integration, in-app event optimization, ARPU targets.

  • Local / multi-location

    Per-lokalizacja geo, store visit conversions, lokalne Search, Google Business Profile signals.

Wgrana wiedza

To nie generyczne AI — to skodyfikowana wiedza marketingowa

Space Ads OS wstrzykuje do kontekstu Claude Code własną bazę wiedzy: ok. 30 utrzymywanych plików w 6 kategoriach — od integracji per kanał, przez przekrojowe koncepty, po branżowe playbooki. Rekomendacje opierają się na realiach platform i doświadczeniu zespołu, nie na zgadywaniu modelu. Każdy plik możesz przeczytać i dostosować pod swój biznes.

Ile to wiedzy?

60+
stron A4 gęstej wiedzy
33 000+
słów skodyfikowanej praktyki
~30
plików w 6 kategoriach

Objętość krótkiego podręcznika branżowego — i całość trafia do kontekstu Claude Code przy każdej sesji, zamiast być zgadywana przez model.

  • Kanały

    Google Ads, Meta, TikTok — każdy plik w 11 stałych sekcjach: struktura konta, bidding, audiencje, kreacja, pomiar, raportowanie, funkcje wycofywane.

  • Analityka

    GA4, Merchant Center, GTM — model danych, schemat zdarzeń i tagowanie, atrybucja po stronie sklepu.

  • Koncepty

    Learning phase, okna atrybucji, testowanie kreacji, Pixel + CAPI, blended ROAS, zgody/ATT — przekrojowo, opisane raz i linkowane z kanałów.

  • Playbooki branżowe

    DTC e-commerce, lead-gen B2C, B2B/SaaS, aplikacje mobilne, local — jak 4 kanały i GA4 grają razem, z benchmarkami KPI i rytmem pracy na 6 miesięcy.

  • Specyfikacje kreacji

    Google, Meta, TikTok, LinkedIn — formaty, wymiary i strefy bezpieczne, których pilnuje agent creative-director.

  • Referencje operatora

    Słownik, szablon briefu klienta, quickstart, tryb agencyjny, katalog agentów i mapa multichannel.

  • tROAS ramp-up

    Jak bezpiecznie podnosić target ROAS bez zabijania learning phase: max ±30% co 5–7 dni, monitoring window minimum 14 dni, oczekuj spadku liczby konwersji w pierwszych 3 dniach po zmianie.

  • Meta Andromeda — full-funnel na poziomie ad seta

    Andromeda optymalizuje na poziomie ad seta, nie pojedynczych kreacji. Spend rozkłada się intencjonalnie nierówno — jeden ad bierze często 60–80% budżetu. Oceniasz portfel ad seta jako całość, nie pauzujesz po metrykach pojedynczej kreacji. Testuj 10+ konceptualnie odmiennych kreacji, nie wariacje tej samej.

  • Conversion lag awareness

    E-commerce: 3–7 dni od kliknięcia do realnej konwersji. B2B / lead gen: 14–30 dni. System nie panikuje, gdy „dzisiejszy" ROAS jest niski — wie, kiedy ocenić wynik.

  • PMax vs Search ROAS comparison

    Jak porównać Performance Max i Search uczciwie, gdy PMax kanibalizuje search brand: wymuszenie breakdown SEARCH-only, korekty na brand traffic, real incremental ROAS.

  • Learning-phase respect

    Kampania w learning to święta krowa: ±30% to absolutny limit zmiany, brak edytowania creative, brak zmian audiences, ad scheduling tylko w trybie ekstremalnym.

To realna przewaga nad generycznym AI. System nie improwizuje odpowiedzi z tego, co model kiedyś przeczytał w sieci — pracuje na strategiach, które nasz zespół sprawdził na żywych kontach reklamowych, spisał i wgrał do narzędzia. Sprawdzona praktyka, nie pewnie brzmiące zgadywanie.

Troubleshooting

Najczęstsze problemy i jak je rozwiązać

Dłuższa wersja w pakiecie: docs/troubleshooting.md.

  • Nie mam Manager Account w Google Ads — co teraz?

    Trzeba założyć MCC (free, ~10 min). Google nie wystawia developer tokenów ze zwykłych kont Google Ads. Kroki: (1) ads.google.com/aw/accounts/managers/ → Create manager account; (2) wybierz "Manage my own accounts" jeśli solo, "Manage other accounts" jeśli agencja; (3) podlinkuj swoje istniejące konto do MCC: Sub-account settings → Link existing account, wpisz 10-cyfrowy Customer ID, zaakceptuj zaproszenie z poziomu zwykłego konta; (4) z MCC: TOOLS → API Center → wnioskuj o developer token (1–2 dni roboczych). Setup-wizard CLI (spaceads-setup) prowadzi krok po kroku.

  • Dostaję 403 z Google Ads API

    Najczęściej: developer token na poziomie Test Account zamiast Basic, albo brak login-customer-id w configu. Sprawdź ~/.config/google-ads/config.yaml — pole login_customer_id musi pasować do MCC, z którego ruszasz API.

  • OAuth do Meta wygasa po 60 dniach

    OAuth bridge oauth.spaceads.agency robi refresh automatycznie tak długo, jak nie cofniesz przyznania w Meta Business Settings. Jeśli widzisz "token expired" — uruchom spaceads-setup --reauth=meta.

  • GA4 zwraca puste sesje

    Najczęstsza pomyłka: w configu wpisany Measurement ID (G-XXXX) zamiast Property ID (numeryczny). Sprawdź clients/<slug>/credentials/ga4.json — pole property_id musi być numerem, nie stringiem zaczynającym się od G-.

  • Smart+ migration nie idzie

    Smart+ wymaga: min 50 konwersji/tydzień, EMQ ≥ 6 dla Pixela, 6+ wariantów kreacji, ROAS w przedziale ±15%. /spaceads-modify migrate-smart-plus pokaże, które warunki nie są spełnione — najczęściej brakuje EMQ albo wariantów kreacji.

  • CLI mówi "subscription inactive"

    Subskrypcja wygasła lub została anulowana. Wejdź na academy.spaceads.agency/account/subscription i reaktywuj. CLI odzyska dostęp w ciągu kilku minut po pobraniu kolejnej opłaty.

  • Audit log w innym timezone niż klient

    Domyślnie logs/changes.jsonl używa UTC. Ustaw zmienną środowiskową SPACEADS_TZ=Europe/Warsaw (lub IANA timezone klienta), żeby timestampy były w lokalnym czasie.

Czas zamienić podgląd na produkt

Subskrypcja miesięczna, faktura natychmiast, dostęp od razu po pierwszym opłaceniu. Anulujesz w każdej chwili.

Aktywuj subskrypcję
Dokumentacja Space Ads OS — komendy, agenci, raporty