t1k:marketing:ua:how-to-optimize
| Field | Value |
|---|---|
| Module | ua |
| Version | 1.13.11 |
| Effort | high |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:ua:how-to-optimizeHow To Optimize UA
Section titled “How To Optimize UA”Standalone diagnostic and remediation playbook for underperforming or policy-blocked UA. Each section is a self-contained loop: a trigger, a read-only diagnostic, a decision gate, and an action with an explicit autonomy boundary.
When to Use
Section titled “When to Use”Activate on: “ad group is limited by policy”, “eligible (limited)”, “misleading ad design”, “disapproved creative”, “why isn’t this ad group spending”, “which creative is blocking the ad group”, “optimize UA”.
Sibling skills own the adjacent surfaces — cross-link, don’t duplicate:
| Need | Skill |
|---|---|
| Campaign structure, bidding (tCPA/tROAS), budget pacing, scaling rules | t1k:marketing:ua:campaigns |
| Creative production, hook rate, rotation cadence, concept testing | t1k:marketing:ua:creatives |
| Install attribution, SKAdNetwork, deferred deep links | t1k:marketing:ua:attribution |
| Adjust RS-API cost/ROAS reporting | t1k:marketing:ua:adjust |
| Google Ads API auth + GAQL reference | t1k:marketing:monetization:googleads |
Play 1 — Ad group limited by policy
Section titled “Play 1 — Ad group limited by policy”Trigger. An ad group shows Ad group is limited by policy in the UI, or
ad_group_ad.policy_summary.approval_status = APPROVED_LIMITED via the API.
The decision rule
Section titled “The decision rule”ad group limited by policy └─ identify the policy topic → ALWAYS report it to the operator └─ isolate the offending asset └─ can the creative spend? ├─ NO → is this account cleared for autonomous removal? (Step 4b) │ ├─ YES → remove the policy creative directly, then report │ └─ NO → present op/target/before→after, ask once, then remove └─ YES → STOP. Escalate to the operator to weigh the decision.The spend check decides whether a removal is safe; Step 4b decides whether it is authorized. Both must pass before anything mutates. Rationale: references/play-1-detail.md.
Step 1 — Resolve the account
Section titled “Step 1 — Resolve the account”Campaign names live in child accounts, not the MCC. Resolve first or every later query returns zero rows:
Query text: references/play-1-detail.md § Step 1.
Run against the MCC, set login-customer-id to the MCC, and issue subsequent queries against the
child customer_id.
Step 2 — Confirm the limitation and name the policy
Section titled “Step 2 — Confirm the limitation and name the policy”approval_status values that matter:
APPROVEDserving normally ·APPROVED_LIMITEDserving but restricted (this is “limited by policy”) ·AREA_OF_INTEREST_ONLYserves only outside the targeted area ·DISAPPROVEDnot serving at all.
policy_topic_entries[].type of PROHIBITED means the content is banned outright, not merely
restricted by geo/age/device. Report the topic to the operator before doing anything else —
this is the “notice me if there are Google Ads policies” obligation, and it is unconditional.
Step 3 — Isolate the offending asset
Section titled “Step 3 — Isolate the offending asset”The ad reports APPROVED_LIMITED; the individual asset reports DISAPPROVED. You must descend to
asset level to find the culprit — the ad-level row never names it.
Run this unsegmented — it is the inventory, not a metrics query. It returns every asset link the ad group has ever had, including the ones that never delivered, which is exactly the set you need to audit; Step 4 joins the delivery metrics onto it.
Filter for rows whose policy_summary.policy_topic_entries is non-empty. Ignore rows already
enabled = false — those were remediated previously.
Step 3b — Check the asset for reuse across the account (MANDATORY)
Section titled “Step 3b — Check the asset for reuse across the account (MANDATORY)”Do not skip this. Creatives are shared across campaigns. The ad group the operator names is usually one of several links to the same asset, and fixing only that one leaves the violation live everywhere else — while the operator, looking at the account, correctly reports “I still see it”.
Remove only the links that individually carry the finding. A link qualifies when that row
shows enabled = true AND a non-empty policy_topic_entries. A link to the same asset that is
clean — no finding on that row — is not a target, no matter how many sibling links are
disapproved. Policy findings are evaluated per ad, so the same creative can genuinely be fine in one
ad group and prohibited in another (different ad context, different surrounding assets, different
Remove only links that individually carry the finding; a clean link to the same asset stays. Run the spend gate per qualifying link. Full reasoning: references/play-1-detail.md.
Asset IDs are account-scoped, so this query covers one child account. If the same creative was uploaded to several accounts it has a different ID in each; sweep per account.
Step 4 — The spend gate
Section titled “Step 4 — The spend gate”Keep Step 3’s inventory rows and join these metrics onto them by resource name:
Query: references/play-1-detail.md § Step 4.
Key on ad_group_ad_asset_view.asset, never asset.id — the joined asset.* fields are not
available once the query is date-segmented (see Gotchas). An inventory row with no matching metrics
row is a zero-delivery link: that is the “cannot spend” branch, not missing data.
Judge “can spend” on the 30-day window, and read three things together:
- Cost. Divide the asset’s cost by the ad group’s total. Below ~0.1% is noise, not delivery.
- Recency. The date of the last impression. If it predates the disapproval, the asset is dead.
- Trend. Compare last-7-days against last-30. Zero in the recent window while the ad group keeps spending is confirmation that Google has stopped serving it.
A disapproved asset commonly shows a small non-zero residue from before the disapproval landed. That residue is history, not current delivery — do not read it as “still spending”. The question is whether it can spend now.
Not spending → check the authorization gate (Step 4b), then remove and report. The spend
analysis says the removal is safe; it does not say it is asked for. Rule 2 of
ad-network-mcp-write-safety.md wants the operator’s consent, and a grant that rule cannot observe
is not an exception to it.
Still spending → stop and escalate. Present cost, share of ad-group spend, impressions, clicks,
and last-served date, and let the operator decide. Never remove a spending creative on your own
judgment — this branch is never covered by the config flag, whatever allowedAccounts says.
Step 4b — The authorization gate (MANDATORY before any removal)
Section titled “Step 4b — The authorization gate (MANDATORY before any removal)”Read .claude/t1k-config-marketing.json (the merged t1k-config-*.json stack; a project layer wins
over the kit layer). Both must hold: adWriteSafety.zeroSpendCreativeRemoval.enabled is true, and
…allowedAccounts contains this account’s customer_id. Compare digits only — the API returns
8933932029, so a hyphenated 893-393-2029 allowlist entry can never match. A missing block, a
missing key, or a false/absent flag all mean not authorized. Evaluate once per account per
run — the answer is a property of the account, not of the link.
- Both hold → remove directly, then report. Do not ask. Execute the mutate (Step 5), verify it, and tell the operator what was removed, from which ad groups, and what it cost them.
- Either fails → present, then ask once. Show the operation, the target (account / campaign / ad group / ad id / asset id) and the before → after — the qualifying links with their 30-day cost — then wait. On a yes, proceed with the whole set for that account; a “go ahead” given before this presentation does not satisfy rule 2. Report afterward.
The spend analysis is a judgement about the asset; the authorization is a statement about the
operator’s intent, and validateOnly: true verifies only request shape — it can never stand in for
the latter. Maintainer decision, including why the default is off: The1Studio/theonekit-marketing#218.
Step 5 — Remove (only through the “not spending” branch)
Section titled “Step 5 — Remove (only through the “not spending” branch)”App campaign assets live on the ad itself, not on a detachable link. Read the current composition:
Then AdGroupAdService.mutate an update with update_mask on the one field that holds the asset
(e.g. ad.app_ad.images), supplying the full list minus the offending asset. Omitting the
update_mask blanks every unlisted field — always scope it.
Before mutating, confirm the remaining count still satisfies the ad’s requirements. Removing one image from five is safe; removing the last video is not.
After the mutate, re-run Step 2. approval_status should return to APPROVED. Re-review is
typically 24–48 hours, so a still-limited reading immediately after the change is expected, not a
failed fix.
Google Ads policy reference — Misleading ad design
Section titled “Google Ads policy reference — Misleading ad design”Disapproval of the asset, and account suspension for repeated violations with a warning at least 7 days beforehand. Editing and resubmitting triggers re-review. The full violation list, why mobile-game UA hits it, and the enforcement text: references/misleading-ad-design-policy.md.
Hard rules
Section titled “Hard rules”Verified against Google Ads API v22, September 2026.
pageSizeis rejected.googleAds:searchreturnsPAGE_SIZE_NOT_SUPPORTED; page size is fixed at 10,000. Paginate withpageTokenalone.ad_group_ad_asset_view.policy_summaryhas no selectable subfields. Selecting.policy_summary.approval_statusthrowsUNRECOGNIZED_FIELD— request the wholepolicy_summaryobject. This differs fromad_group_ad.policy_summary.approval_status, where subfield selection is supported. The two resources are not symmetric.- The ad hides which asset is at fault. Ad-level
APPROVED_LIMITEDwith a populatedpolicy_topic_entriesnames the topic but never the asset. Always descend toad_group_ad_asset_view. APPROVED_LIMITEDstill serves. It is not a stopped ad group. Spend continues on the compliant assets, which is why a policy limitation can sit unnoticed for weeks.- Asset-level cost is attributed, not billed. Treat
metrics.cost_microsonad_group_ad_asset_viewas a delivery-share signal, not an invoice line. - Account timezone drives date ranges.
LAST_30_DAYSresolves in the customer’s timezone (customer.time_zone), not yours. Verify it before reasoning about “yesterday”. - One asset, many ads. A flagged creative is usually linked from several ad groups across
several campaigns. Removing it from the ad group the operator named fixes one link and leaves the
rest live. Always enumerate by
asset.idaccount-wide before declaring the remediation done. - Enumerate account-wide, but act per link. The account-wide sweep is for finding the spread, never for bulk removal. Target only rows carrying their own finding — a clean link to a disapproved asset stays.
- Look at the creative before recommending deletion.
MISLEADING_AD_DESIGNis frequently caused by one removable element — a baked-in “PLAY NOW”/install button, a fake close X, a fake dialog — sitting on otherwise compliant art. Pullasset.image_asset.full_size.urland view it. If the violation is a single element, re-cutting the image keeps the creative’s performance and clears the policy, which strictly beats deleting a converting asset. Only recommend deletion when the whole concept is the violation. - Blank asset IDs on text fields are normal.
headlines/descriptionsinapp_adreturn inline text without asset resource names; only media carries resolvable IDs. - Ad-level
policy_summarygoes stale after the fix. Removing the offending asset clears the asset-level finding immediately, butad_group_ad.policy_summarykeeps reportingAPPROVED_LIMITEDwith the original topic until Google re-reviews (24–48h). Verify a removal againstad_group_ad_asset_view— “no flagged assets remain” — not against the ad-level status. Reading the stale ad-level row as failure will send you chasing a fix that already landed. ad_group_ad_asset_viewkeeps historical links. The link count does not drop when an asset is removed from the ad; the row persists with the policy finding cleared. Count flagged rows, not total rows.- Update the ad, not the ad group ad. Asset lists live on the Ad, so the mutate goes to
AdService(customers/{cid}/ads:mutate) withupdate_mask: app_ad.images— notAdGroupAdService. Dry-run withvalidateOnly: truefirst; it returns{}on success. - Asset links that never delivered are invisible to a windowed query. A link with no impressions in the window produces no row at all, so starting from the 30d/7d metrics silently drops every zero-cost asset — precisely the set the “not spending” branch acts on. Run the unsegmented inventory query (Step 3) first, then join the windowed metrics onto it by resource name (Step 4). The inventory is the report; the metrics only annotate it.
- Read the flag before the branch, not after the mutate. Step 4b is a config read, and a config
read that happens once the write is already sent is theatre. Load
.claude/t1k-config-marketing.json, resolve both conditions, and only then decide which of the two zero-spend paths (silent vs. ask-once) this account is on.
Worked example
Section titled “Worked example”A full walkthrough of this play applied end to end (the spend gate failing, the Step 4b prompt, the Step 3b asset-reuse miss, and the creative re-cut instead of deletion) is in references/worked-example-beatbox3d.md.
Related
Section titled “Related”t1k:marketing:ua:campaigns— bidding, pacing, scalingt1k:marketing:ua:creatives— creative testing and rotationt1k:marketing:monetization:googleads— OAuth2 + developer-token auth, GAQL patterns- Google Ads policy: Misleading ad design · Eligible (limited) · Fix a disapproved ad