Sklik PPC App

CLI aplikace pro správu PPC kampaní na Seznam Sklik přes API Drak (JSON, verze v5). Je pro marketéry a agentury, kteří chtějí kampaně spravovat z terminálu nebo konverzací s Claude Code místo ručního klikání ve webovém Skliku.

Pokrývá kompletní životní cyklus search i obsahových kampaní: kampaně, sestavy, klíčová slova, inzeráty, vylučující slova, výzkum klíčových slov, statistiky. K tomu měření konverzí, retargetingová publika, cílení (regiony / zařízení / rozvrh), obrázkové bannery a kombinovanou (nativní) reklamu.

Autor: Jindřich Fáborský · kurz AI First

[!TIP]
Appka je zdarma a je tvoje. Naklonuj si ji, používej ji, přestav si ji po svém.

Nevíš, jak ji rozjet? Nebo chceš AI v marketingu používat systematicky: řídit z jednoho místa všechny kanály, automatizovat rutinu, postavit si vlastní znalostní bázi a vibe codovat si nástroje na míru své firmě? To učím v kurzu AI First. Tahle appka je v něm vysvětlená i s tím, jak si postavit vlastní.

Součástí repa je i skill pro Claude Code, který appku obaluje.

🆕 Co je nového

Poslední verze je 1.10.1. Celá historie: CHANGELOG.md.

• 1.10.1: oprava jednotek u nakupy-campaigns. Denní rozpočet se tiskl 100× vyšší (250 Kč jako 25 000 Kč) a modifikátory nabídek obráceně. maxCpcMultiplier navzdory jménu není násobič se základnou 100 %, ale znaménkové procento se stejnou konvencí jako DRAK (0 = beze změny, -100 = vypnuto). Specifikace Fénixu tvrdí u obou polí něco jiného než živý účet; díky za ověření patří opět uživateli ArkAngelMichael.
• 1.10.0: nová skupina příkazů Nákupy / feed (API Fénix): feed-status, feed-diagnostics, nakupy-campaigns, nakupy-stats, shop-items. U nákupních kampaní (Seznam Nákupy, dřív Zboží.cz) vidí DRAK jen agregát na kampani a sestavě. Feed, jednotlivé produkty ani rozpad výkonu podle umístění (Seznam × Zboží, typ aukce, zařízení) neukáže vůbec. To teď doplňuje API Fénix; potřebuje vlastní token v .env. Za nápad i za první implementaci děkuji uživateli ArkAngelMichael.
• 1.9.0: výpisy vrací kompletní data. campaigns bralo z API jen prvních 100 kampaní (a --status filtroval až nad touhle useknutou stovkou), groups/ads/banners 500 řádků. Větší účet tak tiše přišel o zbytek a nikde to nebylo vidět. Nově se všechny výpisy i reporty stránkují až do konce. Díky za nahlášení patří studentovi kurzu AI First.
• 1.8.1: opraveno cílení kampaní. --regions posílalo do API holá čísla místo structů (každý pokus o geo cílení končil chybou regions[0] must be struct, not int), --device-bids posílalo desetinná čísla místo celých (must be int, not double) a --schedule-json byl v dokumentaci v tvaru, který API odmítá. Díky za nahlášení patří studentovi kurzu AI First.
• 1.8.0: statistiky umí winRate (podíl vyhraných aukcí, jen u sestav) a --granularity daily pro denní řady; přibyly sloupce exhaustedBudgetShare, impressionMoney/clickMoney, avgCpt, a campaigns teď ukazuje i rotaci reklam (adSelection). Opraveno: CTR se v lidském výstupu tisklo 100× menší (0.01% místo 0.73%); --json se nemění.
• 1.7.2: oprava jednotek conversionValue (100× podhodnocená hodnota konverzí).

💡 Chceš dostávat upozornění na nové verze? Na GitHubu: Watch → Custom → Releases.

Dva způsoby, jak appku používat

A) Orchestrace přes Claude Code (výchozí a nejjednodušší). Appku řídí Claude Code (nebo jiný coding agent) přes přibalený skill: ty zadáváš cíle česky, agent volá CLI, drží bezpečnostní pravidla (schválení před zápisem, --confirm u mazání, atomická výměna inzerátů) a hlídá API limity. Nejrychlejší start: otevři Claude Code a vlož mu prompt typu:

Naklonuj https://github.com/faborsky/sklik-ppc-app, spusť ./setup.sh, nainstaluj mi přibalený skill podle skill/INSTALL.md a pak mi řekni, kam mám vložit svůj Sklik API token.

Claude vše připraví; token pak vlož ručně do .env (soubor je v .gitignore, token nikdy neposílej do chatu ani nikam do kódu). Odteď stačí /sklik-ppc z libovolného projektu. Detaily instalace skillu: skill/INSTALL.md.

B) Vlastní automatizace a agentní řešení (pro pokročilé). Appka je normální CLI stavěné na strojové řízení: --json výstupy, chyby jako {"error": …} na stdout, request-budget vestavěný (neuřídíš API limity omylem). Vezmi si ji do vlastních skriptů, cronů nebo agentních workflow. Kompletní referenci příkazů máš níže v tomhle README a chování API (quirky, limity, status kódy) v docs/api-notes.md.

Požadavky

• Python 3.10+
• Sklik API token (jak ho získat)

Instalace

# Setup skript (vytvoří venv, nainstaluje závislosti, založí .env)
./setup.sh

# Doplň API token do .env
nano .env

Nebo ručně:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # a doplň token

Autentizace

Získání API tokenu

1. Přihlas se do Skliku a otevři www.sklik.cz/settings.
2. Najdi sekci „Přístup k API Drak“.
3. Vygeneruj / zkopíruj svůj API token.
4. Token vlož do souboru .env jako SKLIK_API_TOKEN (viz Konfigurace níže).

Token je heslo k tvému Sklik účtu přes API. Nikam ho nedávej do kódu ani do gitu, patří výhradně do .env (které je v .gitignore).

Konfigurace

Tokeny patří do .env (soubor je v .gitignore, nikdy se necommituje):

SKLIK_API_TOKEN=tvuj-token            # výchozí účet (--account vynechán)
SKLIK_API_TOKEN_CLIENTB=tvuj-token    # volitelný další login → --account clientb

Účty se zjistí z prostředí za běhu. Žádná jména nejsou natvrdo v kódu, takže můžeš mít libovolný počet loginů. Session se po přihlášení cachuje 25 minut do .session_cache_<account>.json (taky gitignored) a automaticky se obnoví při vypršení (401).

Účty vs. spravované účty

Dva nezávislé globální přepínače (uvádějí se před názvem příkazu):

• --account <name>: který login / token se použije. Bez přepínače = default (SKLIK_API_TOKEN); --account <name> čte SKLIK_API_TOKEN_<NAME>.
• --user-id <id>: spravovaný účet pod aktivním loginem (agentura → klientský účet).

python sklik_cli.py account                          # výchozí login
python sklik_cli.py --account clientb account         # jiný login
python sklik_cli.py --user-id 123456 campaigns        # spravovaný účet pod aktivním loginem

suggest a suggest-stats přepínač --user-id tiše ignorují (API metody parametr spravovaného účtu nemají), volej je bez něj. --account funguje normálně.

Použití

Příkazy se spouští přes run.sh (sám aktivuje venv):

./run.sh <příkaz> [přepínače]
# ekvivalent: source venv/bin/activate && python sklik_cli.py <příkaz> [přepínače]

Konvence napříč CLI:

• Ceny v CZK: CLI přijímá i zobrazuje koruny; na haléře (×100) převádí samo.
• --json: strojově čitelný výstup (použij při parsování).
• --confirm: povinný u všech mazacích operací (*-remove).
• Filtry --campaign-id / --group-id / --status se aplikují na straně klienta (API je v restriction nepodporuje).
• Výchozí rozsah statistik je posledních 30 dní.

Účet

./run.sh api-limits            # limity + kolik requestů jsi spotřeboval (60 s / 24 h)
./run.sh api-limits --json     # strukturovaný výstup

Ochrana účtu před zablokováním. Appka počítá každé volání do per-account souboru .rate_limit_<account>.json (přežívá napříč session i paralelními běhy) a kontroluje ho před každým requestem: na 90 % minutového limitu počká, na denním limitu operaci odmítne. Limity bere z api.limits (cache ~1×/den). Counter neřešíš ručně, appka to hlídá za tebe.

Pulse

Souhrn celého účtu jedním voláním, místo řetězení account + campaigns + campaign-stats. Vrátí totály, statistiky po kampaních, delty vůči předchozímu stejně dlouhému období a top movery, předpočítané do kompaktního digestu. Hodí se na levný a rychlý analytický pull.

./run.sh pulse                 # posledních 7 dní vs předchozích 7
./run.sh pulse --days 30       # posledních 30 dní vs předchozích 30
./run.sh pulse --no-compare    # bez srovnání s předchozím obdobím
./run.sh pulse --json          # strukturovaný výstup pro další zpracování

pulse si přes stats.status ověří, že statistiky za celé okno jsou už kompletní. Když ne (typicky dnešek je „preparing“), přidá varování (statsWarning v --json), že čísla a delty jsou zatím z částečných dat.

Kampaně

Cílení (campaign-create / campaign-update):

• --regions: ID regionů oddělená čárkou (číselník: příkaz regions). Nastavení nahrazuje celou sadu regionů. Geo cílení nejde přes API zrušit, API odmítá prázdné pole i nil. Smazat ho jde jen ve webovém rozhraní Skliku.
• --device-bids: modifikátory v % jako desktop:mobile:tablet:other, např. 0:-30:-30:-100. Musí to být celá procenta (API odmítá desetinná čísla).
• --schedule-json (jen update): 7 polí po 24 hodinových hodnotách 0–100, týden začíná pondělím: '[[0,0,…,100,100,…], …×7]'. Hodnota null rozvrh smaže. (CLI přijme a převede i starší tvar {"daySchedule":[{"value":[…]}, …]}, v jakém API rozvrh vrací.)
• --ad-selection, rotace inzerátů (adSelection): weighted (preferuj vyšší CTR, výchozí), random (rovnoměrně, čistý A/B test kreativ), cpa (nižší CPA), cos (nižší CTR)

Sestavy (ad groups)

--max-daily-impression N = frekvenční limit (max. zobrazení na uživatele za den), v Skliku pole maxUserDailyImpression.

Klíčová slova

name ani matchType klíčového slova nelze měnit, slovo je nutné smazat a vytvořit znovu.
keyword-set je upsert: chybějící slova přidá, existujícím upraví CPC/URL, dříve smazaná obnoví. S --remove-others navíc smaže všechna slova, která v payloadu nejsou: plná synchronizace sestavy podle seznamu.

Inzeráty (ETA)

Změna textu inzerátu = ad-replace, NIKDY ruční ad-remove + ad-create. Sklik neumí text upravit na místě: jakákoli změna kreativy udělá přes ads.update atomickou výměnu na serveru (smaže starý + vytvoří nový v JEDNÉ operaci, vrátí newAdIds). Když nový inzerát neprojde validací (typicky ad_duplicate_in_db), původní zůstane nedotčený. Ruční remove+create tuhle jistotu nemá. Když selže create po removu, sestava tiše ztratí inzerát (reálně se to stalo). ad-replace načte stávající inzerát, aplikuje jen zadaná pole (zbytek zachová), předvaliduje přes ads.check a pak provede atomickou výměnu. Jen textové (eta) inzeráty.

Kombinovaná (nativní) reklama

Formát pro obsahovou síť, kterým se zobrazuje i nativní reklama v článcích na webech Seznamu. Sklik z dodaných textů a obrázků automaticky skládá výslednou podobu (nativní pozice v článku, responzivní sloty, branding). Konkrétní umístění nevybíráš.

Výpis přes ads (adType: combined), statistiky přes ad-stats, smazání přes ad-remove. Obrázky: lokální cesta nebo URL (jpg/png/gif, max 1 MB), CLI je zakóduje samo.

Pozor: Sklik z textů tiše odstraňuje zakázané znaky (třeba dlouhou pomlčku z titulku), bez chyby i bez warningu. Po vytvoření si finální znění ověř přes ads --group-id X --json. Kombinovanou reklamu nelze upravit na místě (ad-replace je jen pro textové inzeráty kvůli obrázkům): vytvoř nový inzerát, ověř, a teprve pak smaž starý (create-first, aby selhaný create nikdy nesmazal poslední inzerát).

Vylučující klíčová slova

negatives umí vypsat jen skupinové vylučovačky (--campaign-id filtruje přes sestavy dané kampaně). Kampaňové vylučovačky (negative-add --campaign-id) jsou v API write-only: zapsat jdou, ale zpětně vypsat ne. Ověříš je jen ve webovém rozhraní Skliku.

Výzkum klíčových slov

Vyhledávací dotazy

Sitelinky

sitelink-assign NAHRAZUJE celou sadu přiřazených sitelinků kampaně/sestavy, vždy pošli kompletní seznam, ne jen přírůstek. Přejmenování sitelinku (sitelink-update --name) vytvoří NOVÉ ID (server dělá remove+create), CLI nové ID vypíše; změna --url ID zachová.

Konverze (definice měření)

Konverze = pojmenovaná definice cílové akce (nákup, registrace…) a její hodnoty. CLI spravuje definice; samotné měření (pixel / SEM) žije na webu.

Pozn.: Účty se zapnutým SEM (Seznam Event Measurement) conversions.* metody používat nemohou, CLI v takovém případě vypíše srozumitelnou hlášku. Metoda listConversionTypes je na straně Sklika nefunkční (HTTP 500), proto conversion-types odvozuje typy z existujících konverzí.

Retargeting (publika)

Publikum jde napojit jen na sestavy obsahových kampaní. Pokus o napojení smazaného seznamu vrací 406 Bad values bez bližší diagnostiky, zkontroluj deleted ve výpisu retargeting --json.
Vyloučení publika (retargeting-exclude) funguje na úrovni kampaně i sestavy, typicky „vyluč stávající zákazníky z akviziční kampaně“. Na rozdíl od napojení funguje i na search kampaních.

Obrázkové bannery

Statické bannery (jpg/png/gif) pro obsahovou síť. Pro HTML5 bannery použij jiný nástroj, tady jde o statické formáty.

--image přijme lokální soubor i veřejnou URL, CLI obrázek načte a pošle do Skliku zakódovaný (base64). Drž se povolených formátů z banner-formats (pevné rozměry, ≤ 250 KB).
banner-download čte image.url (staré pole imageURL je deprecated) a uloží kreativy lokálně, což se hodí pro verzování kreativ do repa před výměnou. Výměna banneru = vytvoř nový a teprve pak smaž starý (create-first).

Umístění (cílení na konkrétní weby)

Cílení obsahových sestav na konkrétní weby (v Skliku „umístění“). Vzor je doména nebo cesta: "mediar.cz", "www.e15.cz/byznys".

Pozor: Nová obsahová sestava bez umístění běží po celé obsahové síti. Když chceš cílit na konkrétní weby, přidej umístění před aktivací kampaně.
Quirky vyloučených umístění (ověřeno 2026-07): (1) API ve výpisu nevrací text vzoru, placements-excluded ukáže jen ID, sestavu a datum; text vidíš ve web UI, tak si ho po placement-exclude poznamenej (ID se vrací). (2) Smazané vyloučení blokuje opětovné vyloučení stejného vzoru (group_pattern_duplicity), místo nového create použij placement-exclude-restore se starým ID.

Cílení obsahové sítě: zájmy / témata / úmysly

Tři dimenze cílení obsahových sestav nad rámec umístění a publik: zájmy (interest, dlouhodobé zájmy uživatele), témata (theme, tematika webů, kde se reklama zobrazí) a úmysly (intend, nákupní záměr). Všechny sdílejí stejné příkazy s přepínačem --type interest/theme/intend; váží se na sestavu.

Mazání je soft-delete: opětovné přidání stejné kategorie po smazání vrací 409 entity_already_exists, použij targeting-restore se starým ID (CLI výpisy smazané položky skrývají, ID najdeš v původním výstupu targeting-add/targeting-remove).

./run.sh targeting-categories --type theme                       # jaká témata existují
./run.sh targeting-add --type theme --group-id 123 --category-id 102   # cíl na Auto-moto
./run.sh targeting-exclude --type theme --group-id 123 --category-id 103  # vyluč Bulvár
./run.sh targeting --type theme --group-id 123                   # co je nastavené

Sdílené rozpočty

Jeden denní rozpočet sdílený více kampaněmi. Přiřazení kampaní se řídí na rozpočtu (ne přes campaign-update).

Nákupy / feed (API Fénix)

Seznam Nákupy (dřív Zboží.cz): feed, diagnostika položek, modifikátory nabídek a statistiky rozpadlé podle umístění. Jede přes API Fénix (api.sklik.cz/v1), což je jiné rozhraní a jiný token než zbytek CLI:

• Vygeneruj si Fénix refresh token ve webovém rozhraní Skliku a vlož ho do .env jako SKLIK_FENIX_REFRESH_TOKEN (pro pojmenovaný účet SKLIK_FENIX_REFRESH_TOKEN_<NAME>). Token z DRAKu tu nefunguje.
• Každé volání potřebuje premiseId, tedy ID provozovny/obchodu, ne kampaně: z --premise-id, nebo z SKLIK_FENIX_PREMISE v .env.
• Přístupový token (platnost 1 h) se cachuje v .fenix_cache_<account>.json. --user-id funguje i tady (Fénix bere spravovaný účet už při vydání tokenu).

Dvě konvence se tu liší od zbytku appky:

• Statistiky a ceny u položek feedu jsou v korunách, ne v haléřích. Výjimka je denní rozpočet kampaně: budget.dayBudget i exhaustedDayBudget jsou v haléřích (endpoint nákupních kampaní vrací hodnoty rovnou z DRAKu). V lidském výstupu se převádí, --json vrací syrová data z Fénixu.
• Modifikátor nabídky je znaménkové procento, stejně jako v DRAKu: 0 = beze změny, +20 = +20 %, -100 = umístění vypnuté. Hodnota se dá z nakupy-campaigns přepsat do campaign-update --device-bids bez přepočtu. Umístění, u kterého modifikátor nastavený není, se ve výpisu vůbec neobjeví. Modifikátory podle webu a typu aukce jde přes API jen číst, měnit se dají výhradně ve webovém Skliku; podle zařízení je zapisuje DRAK.

Příklady

# Výzkum klíčových slov
./run.sh suggest --query "kurz ai" --related --limit 30

# Sestavení kampaně shora dolů
./run.sh campaign-create --name "AI kurzy - Search" --day-budget 300 --type fulltext
./run.sh group-create --campaign-id 123 --name "Obecné" --cpc 8
./run.sh keyword-create-batch --group-id 456 \
  --keywords-json '[{"name":"kurz ai","matchType":"phrase","cpc":12},{"name":"ai školení"}]'
./run.sh ad-create --group-id 456 \
  --headline1 "Kurz AI pro firmy" --headline2 "Prakticky a hned" \
  --description1 "Naučte se AI využívat v praxi. Přihlaste se ještě dnes." \
  --final-url "https://example.cz/kurz"

# Vyloučit nerelevantní dotazy (campaign-level)
./run.sh negative-add-batch --campaign-id 123 --keywords-json '["zdarma","free","práce"]'

# Cílení: snížit nabídku na mobilu/tabletu, vyloučit ostatní zařízení
./run.sh campaign-update --campaign-id 123 --device-bids 0:-30:-30:-100
./run.sh campaign-targeting --campaign-id 123

# Statistiky za konkrétní období (JSON pro další zpracování)
./run.sh campaign-stats --campaign-id 123 --date-from 2026-01-01 --date-to 2026-01-31 --json

# Vyhledávací dotazy, které spustily reklamu
./run.sh search-queries --campaign-id 123 --limit 50

# Nákupy (Seznam Nákupy) — zdraví feedu, kde se výkon ztrácí, co není spárované
./run.sh feed-diagnostics
./run.sh nakupy-stats --split webType,deviceType --date-from 2026-08-01 --date-to 2026-08-31
./run.sh shop-items --unpaired --all --json

# Měření a publika
./run.sh conversions
./run.sh retargeting
./run.sh banner-formats

# Kombinovaná (nativní) reklama pro obsahovou síť
./run.sh combined-create --group-id 789 \
  --short-line "Kurz AI pro firmy" \
  --long-line "Naučte se AI využívat v každodenní praxi" \
  --description "Praktický videokurz pro marketéry a podnikatele." \
  --company-name "Example s.r.o." \
  --final-url "https://example.cz/kurz" \
  --image-landscape ./obrazky/landscape_1200x628.jpg \
  --image-square ./obrazky/square_1200x1200.jpg

Skill pro Claude Code (/sklik-ppc)

Součástí repa je i skill pro Claude Code ve složce skill/. Ten obaluje tohle CLI a přidává PPC know-how (pravidla inzerátů, struktura kampaní, scénáře pro search i bannery), takže můžeš celé kampaně spravovat konverzací: /sklik-ppc create search, /sklik-ppc optimize, …

Skill ti dává mechaniku (jak věci udělat nástrojem) a pravidla (co Sklik povoluje). Strategii průběžné optimalizace si nastavíš podle svých cílů.

➡️ Instalace skillu: viz skill/INSTALL.md (zkopíruj složku do ~/.claude/skills/ a nastav cestu k appce).

Struktura projektu

sklik-ppc-app/
├── sklik_cli.py        # Tenký entrypoint (volá sklik.cli.main)
├── sklik/              # Balík s implementací
│   ├── api.py          #   engine: auth, session, rate-limit, _api_call, stránkování, chyby
│   ├── fenix.py        #   engine pro REST API Fénix (Seznam Nákupy: feed, diagnostika, statistiky)
│   ├── formatting.py   #   převod CZK⇄haléře + JSON výstup
│   ├── reports.py      #   dvoukrokový report helper
│   ├── images.py       #   načítání/kódování obrázků (bannery + combined)
│   ├── cli.py          #   argparse + dispatch
│   └── commands/       #   jeden modul na doménu (ads, campaigns, keywords, …)
├── requirements.txt    # Závislosti (requests, python-dotenv)
├── setup.sh · run.sh   # Instalační / spouštěcí skript (aktivuje venv)
├── .env.example        # Šablona pro tokeny
├── CLAUDE.md           # Signpost pro Claude Code (+ dokumentační mapa)
├── docs/api-notes.md   # Hutná reference chování API Drak
├── CHANGELOG.md        # Historie verzí
├── .env                # Tokeny (NEVERZOVAT)
└── skill/              # Skill pro Claude Code (/sklik-ppc) + INSTALL.md

API poznámky

• Protokol: JSON-RPC POST na https://api.sklik.cz/drak/json/v5/{metoda}. Endpoint je připnutý na v5, aby se CLI tiše nerozbilo při major změně API.
• Reporty jsou dvoukrokové: createReport (filtry + období) → readReport (stránkování + sloupce).
• API nepodporuje filtry na nadřazené entity (campaign.ids, group.ids, status) v restrictionFilter, proto se aplikují na straně klienta, ale až nad kompletním seznamem.
• Výpisy jsou kompletní, appka je sama stránkuje. Metody *.list vrací najednou nejvýš 5000 řádků (statsDataLimit) a nehlásí, že něco useknuly (v odpovědi není celkový počet). CLI proto prochází offsety až do konce: campaigns, groups, keywords, negatives, ads, banners i statistiky vrací celý účet. Do verze 1.8.1 tu byly natvrdo zadané stropy (kampaně 100, sestavy/inzeráty/bannery 500 řádků) a větší účet tiše přišel o zbytek.
• Příklady použití API Drak: github.com/seznam/sklik-api-examples.
• API Fénix (Seznam Nákupy) je samostatné REST rozhraní na https://api.sklik.cz/v1 s vlastní autentizací (refresh token → hodinový access token) a vlastními konvencemi (koruny místo haléřů, násobiče místo přirážek). Dokumentace: api.sklik.cz/fenix, specifikace: api.sklik.cz/v1/openapi.json.

Kompletní chování API (kvirky reportů, bezpečná výměna inzerátů, bannery, konverze, retargeting, rate limity, stavové kódy): docs/api-notes.md.

Licence

MIT, viz LICENSE.

Autor

Jindřich Fáborský, marketér a lektor. Vibe coding a AI v marketingu učím v kurzu AI First.

Sklik PPC App používám na vlastní kampaně a v kurzu je doprovodným materiálem k 7. lekci, která ukazuje, jak vibe coding zapojit do každodenní marketingové práce. Další appky pro foundery a marketéry najdeš na faborsky.cz/appky.