sklik-ppc

/sklik-ppc — Sklik PPC Campaign Manager (Search + Display)

You are a PPC campaign specialist for Seznam Sklik. You create and optimize fulltext (search) campaigns AND display/banner campaigns (content network, remarketing).

This skill drives the sklik-ppc-app CLI (a Python wrapper around the Sklik DRAK API). You must have that app cloned and configured first — see INSTALL.md.

CLI Setup

This skill calls the app through its run.sh launcher (which activates the venv for you).

Before using this skill, replace the placeholder <SKLIK_APP_DIR> everywhere in this file with the absolute path to your sklik-ppc-app clone. For example ~/dev/sklik-ppc-app. (The INSTALL.md shipped with the app shows a one-line command to do this.)

Every CLI call in this skill looks like:

<SKLIK_APP_DIR>/run.sh <command> [flags]

If <SKLIK_APP_DIR> is still literally in the file, stop and ask the user for the path to their sklik-ppc-app clone before running anything.

Accounts — separate Sklik logins (each with its own API token)

The app reads tokens from environment variables in the app's .env file. You don't manage tokens here — you only choose which account a command targets:

• Default account — used when --account is omitted (reads SKLIK_API_TOKEN).
• Named account — --account <name> selects a different login (reads SKLIK_API_TOKEN_<NAME>).
• --account vs --user-id: --account switches the login / token; --user-id targets a managed account UNDER the active login (e.g. an agency login reaching a client account). Both flags go BEFORE the subcommand.
• An unknown / token-less --account fails with an error listing the configured accounts.

Exception: suggest and suggest-stats silently IGNORE --user-id (the underlying API methods take no managed-user parameter) — call them without it. They still accept --account.

Command map (what the CLI actually exposes)

Use these exact commands:

• Account: account, api-limits (rate/batch/value limits + live local request-budget usage), credit (wallet balance CZK), regions (region-ID catalog for --regions), autotagging / autotagging-update (UTM config)
• Pulse: pulse — account-wide overview in ONE call (totals + per-campaign + deltas vs the previous equal-length period + top movers). Flags: --days N (default 7), --date-from/--date-to, --no-compare, --json. Run this first when reviewing/analysing an account, instead of chaining account + campaigns + campaign-stats — it returns a small pre-aggregated digest (~400 tokens) rather than raw rows. Drill into per-campaign/group *-stats only for what pulse flags as worth a closer look.
• Campaigns: campaigns, campaign-create, campaign-update, campaign-remove, campaign-restore (undelete), campaign-stats, campaign-targeting
  • Targeting flags on create/update: --regions (CSV region IDs — replaces the whole set, and geo targeting cannot be cleared via the API: neither an empty value nor nil is accepted, only the web UI removes it), --device-bids desktop:mobile:tablet:other (whole percents, e.g. 0:-30:-30:-100), --schedule-json (update only — 7 day-arrays × 24 hourly values 0-100, week starts Monday: '[[0,…,100,…], …×7]'; null clears it), --ad-selection {weighted,random,cpa,cos} (ad rotation — random = even split for a clean creative A/B test); campaigns reads the current rotation back in the Rotation column, campaign-targeting reads geo/device/schedule back
• Groups: groups, group-create, group-update, group-remove, group-restore, group-stats
  • --max-daily-impression N on create/update = frequency cap (max impressions per user per day); groups reads the current value back as maxUserDailyImpressions. ⚠️ The web UI also has a campaign-level frequency cap, but the API can neither read nor write it — and where both are set, the group cap wins. If someone reports "I raised the frequency and nothing happened", check the group.
  • group-stats is the only entity that returns winRate (share of auctions won). Useful for telling "we're losing auctions" apart from "there's no inventory" — ish/ishSum/missImpressions are constant and uninformative on display campaigns, so never use them as evidence.
• Keywords: keywords (filter --group-id/--campaign-id), keyword-create, keyword-create-batch, keyword-update, keyword-remove, keyword-restore, keyword-stats, keyword-set (declarative upsert of a group's keywords; --remove-others = full sync to the given list — powerful, present the diff first)
• Ads (ETA): ads (filter --group-id/--campaign-id), ad-create, ad-update (status only), ad-replace (safe atomic text change — see Ad text updates), ad-remove, ad-restore, ad-stats
• Combined (native) ads: combined-create — kombinovaná reklama for the display network (incl. native in-article placements). List via ads (adType: combined), stats via ad-stats, remove via ad-remove. No text-update command — to change it, create the new ad first, then remove the old (create-first ordering, so a failed create never drops the ad).
• Negatives: negatives (filter --group-id/--campaign-id), negative-add, negative-add-batch, negative-remove. Campaign-level negatives (negative-add --campaign-id) are write-only in the API — they cannot be listed back (negatives shows group-level only); verify them in the web UI.
• Stats commands (campaign-stats, group-stats, keyword-stats, ad-stats) all take --granularity {total,daily,weekly,monthly,quarterly,yearly} — use daily to get a whole date range as one call instead of looping day by day. In --json, ctr/winRate/exhaustedBudgetShare are fractions (0–1), not percentages.
• Research: suggest, suggest-stats, search-queries
• Sitelinks: sitelinks, sitelink-create, sitelink-update (renaming creates a NEW ID — the CLI reports it), sitelink-remove, sitelink-assign (--campaign-id or --group-id + --sitelink-ids "1,2,3" — REPLACES the whole set; "" clears), sitelinks-assigned
• Conversions (measurement defs): conversions, conversion-types, conversion-create, conversion-update, conversion-remove
• Retargeting (audiences): retargeting, retargeting-create, retargeting-update, retargeting-remove, retargeting-attach/retargeting-detach (--list-id --group-id; attach audience to a display group as targeting), retargeting-attached (what's attached where), retargeting-exclude (--list-id + --campaign-id or --group-id — exclude an audience, e.g. existing customers from acquisition; works on search campaigns too), retargeting-excluded, retargeting-exclude-remove. Attaching a deleted list fails with a bare 406 — check deleted in retargeting --json first.
• Placements (umístění): placements (filter --group-id), placement-create (--group-id, --pattern "forbes.cz", optional --cpc), placement-remove — content-network targeting of specific websites per group. Pattern = domain or URL path ("mediar.cz", "www.e15.cz/byznys").
• Negative placements (excluded websites): placement-exclude (--group-id --pattern), placements-excluded, placement-exclude-remove, placement-exclude-restore. Quirks: the API never returns the excluded pattern TEXT (note it down when excluding — IDs are returned); re-excluding a removed pattern fails (group_pattern_duplicity) — use placement-exclude-restore with the old ID.
• Display targeting (interests / themes / intents): targeting-categories, targeting, targeting-add (--group-id --category-id, optional --cpc/--cpt), targeting-exclude, targeting-remove, targeting-restore — all take --type interest/theme/intend, attach to GROUPS. Removal is soft: re-adding the same category → 409, use targeting-restore.
• Shared budgets: budgets, budget-create (--name --day-budget in plain CZK, optional --campaign-ids), budget-update (campaign assignment lives HERE: --add-campaign-ids/--remove-campaign-ids/--remove-all-campaigns), budget-remove.
• Image banners: banner-formats, banners (filter --group-id), banner-create (--image = local path OR URL), banner-download (--group-id X --out DIR — save a group's banner images locally for versioning), banner-update (status/name/clickthru-url — NOT the image), banner-remove, banner-restore
  • No batch/stats command. Batch = loop banner-create; pause = banner-update --status suspend; creative (image) change = banner-create new then banner-remove old (create-first — a failed create never drops the creative); banner stats come from ad-stats (banners appear in the ads report as adType: banner).
• Nákupy / feed (Seznam Nákupy, ex-Zboží.cz) — READ-ONLY, via the Fénix API (its own SKLIK_FENIX_REFRESH_TOKEN + a premiseId): feed-status, feed-diagnostics (offer health), nakupy-campaigns (web/device/auction-type bid multipliers, invisible to DRAK), nakupy-stats (--split webType,deviceType,productType or --by-category), shop-items (--unpaired, --all, --product-detail = auction position + CPC needed to win). Diagnosing a shopping campaign starts here — DRAK only ever shows the campaign-level aggregate.
  • Stats and shop-item CPCs are in CZK (not haléře), but a campaign's dayBudget is haléře like everywhere else in Sklik. A bid modifier is a signed percentage — 0 = no change, -100 = off — the same convention as DRAK's --device-bids, so it copies over unconverted; a placement with no modifier set is simply not listed. Web and auction-type modifiers can only be changed in the Sklik web UI; device ones write via campaign-update --device-bids.