Google Ads Manager

Google Ads Manager

Overview

Manage Google Ads campaigns through small Python scripts that call the official google-ads API client (v25). Covers the full lifecycle: reporting, creating campaigns, updating budgets/bids/status/targeting, and managing negatives & geo.

Core principle — never spend money by accident. Every mutating operation is validated (validate_only=True) and printed as a plain-language plan BEFORE anything is applied. Nothing touches the account until the user has seen the plan and explicitly approved it.

All scripts live in scripts/ and share auth via _client.py and the safety gate via _common.py. Config/credentials live outside this folder (see SETUP.md) — never read or write credentials inside the skill.

Prerequisite gate — always run first

The library is installed in a dedicated venv. Run every script with that interpreter (not the system python3):

~/.config/google-ads/venv/bin/python scripts/doctor.py

Tip: alias gads-py="$HOME/.config/google-ads/venv/bin/python" then gads-py scripts/<name>.py ….

Before any operation, confirm setup works with doctor.py (above).

If it reports any FAIL, STOP and walk the user through SETUP.md. Do not try to run other scripts against a broken config — you'll just get opaque auth errors. Two gotchas doctor.py flags:

• Service-account delegation needs the impersonated_email to be a Workspace user with Ads access, with domain-wide delegation enabled.
• A fresh developer token has test-account access only until Google approves Basic access — production accounts will error until then.

Intent → script routing

Details:

• Keyword research — keyword_ideas.py (Keyword Planner). Read-only, no spend. Ideas mode discovers keywords from --seed/--url; --historical gets metrics for a keyword list. Returns avg monthly searches, competition, and top-of-page bid ranges — use these to pick keywords and set bids before building a campaign spec. See reference/keyword-planner.md.
• Reporting — report.py --list-presets to see presets. Read-only, safe to run freely. Formats: --format table|csv|json.
• Create — write a JSON spec per reference/campaign-spec.md, then run create_campaign.py. Campaigns default to PAUSED.
• Update / assets — see each script's --help; ids usually come from a report.py query first.

MANDATORY safety workflow for every mutating script

create_campaign.py, update_entity.py, and manage_assets.py all take a --confirm flag. Without it they run validate_only and print the plan only.

Follow this sequence EVERY time — no exceptions:

1. Run the script without --confirm (dry run).
2. Show the printed plan to the user in chat.
3. Wait for the user to explicitly approve.
4. Only then re-run the same command with --confirm.

You MUST NOT pass --confirm in the same step you first build a command. The user has to see the validated plan first.

Red-flag rationalizations — STOP if you think any of these

MANDATORY before proposing or adding keywords

Never propose keywords from search volume alone. Volume without relevance buys irrelevant clicks. Before suggesting or adding ANY keyword you MUST:

1. Understand the product and confirm with the user — what it does and how (e.g. AI vs OCR), its outputs (e.g. Excel), audience, and what it is NOT (e.g. no API). Inspect the landing page; when unsure, ASK.
2. Pull the live ad's assets (RSA headlines/descriptions + final URL) and check every candidate keyword is supported by the ad copy AND landing page.
3. If a cluster isn't supported, exclude it or add supporting copy first (update_ad.py) — never add unsupported keywords blind.
4. Filter by intent — freebie terms → negatives; wrong audience/tech mismatch → exclude.
5. Dry-run → show plan → user confirms → apply.

Full procedure: reference/keyword-research-workflow.md. This is a hard rule — the "propose keywords blind" shortcut is exactly what it prevents.

Red-flag rationalizations — STOP (keyword edition)

Known gotchas (Google Ads API v25)

• Check customer.currency_code FIRST. All budgets/bids/metrics are in the account currency, not USD. (This account is MXN — a "131" bid = 131 pesos.)
• campaign.contains_eu_political_advertising is REQUIRED on create (create_campaign.py defaults it to DOES_NOT_CONTAIN). Enum name: EuPoliticalAdvertisingStatusEnum.
• campaign.start_date / campaign.end_date are NOT valid GAQL field names.
• Amounts are in micros (× 1,000,000); scripts convert automatically.
• Run scripts with the venv python (~/.config/google-ads/venv/bin/python); it forces the public certifi CA bundle (fixes corporate-network TLS, fails closed).

Reference (load only when needed)

• SETUP.md — one-time credential/delegation setup.
• reference/gaql-cookbook.md — GAQL presets and ad-hoc queries.
• reference/campaign-spec.md — JSON schema for create_campaign.py.
• reference/keyword-research-workflow.md — MANDATORY keyword process (above).
• reference/diagnostics.md — "why zero/low metrics?" decision tree; automated by diagnose_campaign.py.

Notes

• Amounts are entered in normal currency units; scripts convert to micros.
• Single-account setup: login_customer_id in the config is the target account.
• Errors surface as per-operation messages with field paths and actionable hints (see _common.handle_google_ads_exception).