Skip to content

Match Google Ads advice to Google's documentation: Search language targeting, the 5x budget claim, Lost IS (budget), Learning status - #138

Open
illia-sapryga wants to merge 1 commit into
kLOsk:mainfrom
illia-sapryga:fix/google-guidance-accuracy
Open

illia-sapryga wants to merge 1 commit into
kLOsk:mainfrom
illia-sapryga:fix/google-guidance-accuracy

Conversation

@illia-sapryga

Copy link
Copy Markdown
Contributor

Hi Daniel,

Four statements AdLoop makes about Google Ads no longer match Google's own documentation. This PR corrects them in the rules, the tool messages and one read insight. Each change is tied to a Google page, quoted below.

1. Search campaigns: language_ids is no longer required

draft_campaign rejected a draft without language_ids, and the rules said "Language targeting is mandatory".

Google retired manual language targeting for Search campaigns in late September 2026:

  • Feature deprecations, entry dated 2026-09-30: "Manual language targeting (CampaignCriterion.language) is no longer supported for Search campaigns, AI Max for Search campaigns, and Performance Max ads shown on Google Search. Instead, ads automatically match to users based on the language of your ad creatives and landing pages alongside user language preferences. Adding or updating CampaignCriterion.language on Search campaigns fails with a ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT error, though existing language criteria are still returned in queries and can be removed using CampaignCriterionService ... Stop setting language criteria when creating or updating Search campaigns."
  • About language targeting: "Search Campaigns: The campaign-level language targeting setting will be removed. Search ads will automatically match based on the language of your ads." and "Shopping ads within Performance Max are not affected by language settings."
  • Announcement: "Effective late September 2026".

What changes:

  • draft_campaign: language_ids is optional (_StrListOpt = None). Geo targets stay required.
  • When language_ids is passed, it is still sent unchanged and the preview carries a warning with Google's wording.
  • update_campaign: language_ids=[] is accepted and removes the campaign-level language criteria, which is the one operation Google still documents for Search. The preview warns that on campaign types that still take language targeting this can widen who sees the ads.
  • Rules, the startup instructions, both docstrings and the create-campaign command say the same thing. The language ID table stays, marked as being for the Keyword Planner tools and for campaign types that still use it.

One thing I could not confirm, and why the code does not refuse. The documentation says creating the criterion fails. On 2026-11-16, on API v25, a validate_only mutate that removed and re-created a language criterion on a live Search campaign was accepted without an error (two runs through confirm_and_apply(dry_run=true), one of them adding a second language). I found nothing in Google's pages about a version threshold, a rollout schedule or a validate_only exception that would explain it. So this PR stops asking for the setting and tells the user what Google says, and leaves the verdict to the dry run. If you see the documented error in your own validate-only checks, a hard refusal would be a small follow-up.

2. The "5x target CPA" warning said "Google recommends"

draft_campaign and update_campaign warned: "Google recommends at least 5x target CPA ... for sufficient learning data."

I could not find that recommendation on any Google page. What Google does publish, in How to fix Google Ads campaigns not running or low traffic: "A good guideline is to set it at least 10 times your expected Cost-Per-Click (CPC) or 2 to 3 times your Target CPA."

The warning keeps the 5x threshold and now says: "5x is AdLoop's rule of thumb, not a Google requirement; Google's low-traffic troubleshooting guide suggests a daily budget of 2 to 3 times the target CPA." The rules and the two commands are worded the same way. The threshold itself is your call; this only removes the attribution.

3. Lost IS (budget) on Maximize conversions and Maximize conversion value

get_campaign_performance flags converting campaigns that lose 20% or more of Search impression share to budget ("They run out of budget while converting"), and the rules say "those can absorb more budget".

About Maximize conversions bidding: "We don't recommend using the impression share 'Lost IS (budget)' column in Google Ads with Maximize conversions because the column is incompatible with the bid strategy. Maximize conversions or Maximize conversion value bid strategies are designed to spend the full daily budget, and are 'limited by budget' by design".

That applies when no target is set. With a target the strategy may not spend the full budget (MaximizeConversionValue: "If the target ROAS is high, the bid strategy may not be able to spend the full budget"), and the API reports the same bidding_strategy_type either way. So the target has to be read.

What changes:

  • When a flagged campaign is on MAXIMIZE_CONVERSIONS or MAXIMIZE_CONVERSION_VALUE, one extra query reads its target, from the campaign or from its portfolio strategy. No such campaign, no extra query.
  • Each flagged entry gains bidding_strategy_type. Entries on the two Maximize strategies get budget_share_reliability: "unreliable" when no target is set, "unknown" when the target could not be read (a portfolio the account cannot read, a missing row, a failed lookup). Entries without the key read as before.
  • Three insights instead of one: the existing one for campaigns the column works with, one for untargeted Maximize campaigns ("Do not read that as room for more budget ..."), and one for unknown ("Treat that share as unconfirmed ..."), which includes the lookup error when there was one.
  • Campaigns the column works with are listed first, so the 10-entry (5 in compact mode) cut cannot push them out.
  • The dashboard's "held back by budget" alert leaves out entries that carry the key.

Not changed: the dashboard table still shows the raw "Lost to budget" percentage for every campaign.

4. "Learning" status

The rules said: "Don't edit campaigns that are in an active learning phase ... Wait until the learning phase completes before making changes", and told the assistant to warn that "changes will restart the learning phase".

About Smart Bidding learning: "Changes to budgets, targets, creatives, or targeting settings (such as location or audience) never remove your historical data or trigger 'Learning' status." The status "never lasts more than 7 days" and follows a bid strategy that was "recently created or reactivated", "Campaigns, ad groups, or keywords" being "added to or removed from the bid strategy", or conversion goals that "have significantly changed".

The rules and the optimize-campaign command now say that, and keep the two cautions Google does give: new or edited ads go through review before they serve (About the ad review process: "Changes to your ad or assets restart the review process and may cause delays"), and several target changes within one conversion cycle are best avoided.

Before and after

Tool output on main and on this branch, same inputs (fake config, no account):

main
--- draft_campaign without language_ids
{
  "error": "Validation failed",
  "details": [
    "language_ids is required — campaigns must target at least one language (e.g. ['1001'] for German, ['1000'] for English)"
  ]
}
--- draft_campaign with language_ids=['1000']
{
  "changes.language_ids": [
    "1000"
  ]
}
--- draft_campaign, TARGET_CPA 50, daily budget 100 (no language_ids where allowed)
{
  "warnings": [
    "Daily budget 100.00 USD is less than 5x target CPA 50.00 USD. Google recommends at least 5x target CPA (250.00 USD/day) for sufficient learning data."
  ],
  "changes.language_ids": [
    "1000"
  ]
}
--- update_campaign language_ids=[]
{
  "error": "Validation failed",
  "details": [
    "language_ids cannot be empty — provide at least one language"
  ]
}
--- get_campaign_performance: three converting Search campaigns, each losing 35% of impressions to budget
insights: [
  "3 converting campaign(s) lose at least 20% of Search impression share to budget: Maximize, no target (35.0% lost to budget), Maximize, target CPA set (35.0% lost to budget), Target CPA (35.0% lost to budget). They run out of budget while converting; compare their CPA with the account before moving budget to them."
]
budget_limited_converters: [{"name": "Maximize, no target"}, {"name": "Maximize, target CPA set"}, {"name": "Target CPA"}]
this branch
--- draft_campaign without language_ids
{
  "changes.language_ids": []
}
--- draft_campaign with language_ids=['1000']
{
  "warnings": [
    "Google retired manual language targeting for Search campaigns in late September 2026: Search ads now match on the language of the ads and landing page plus the user's language preferences. Google's API documentation tells developers to stop sending language criteria for Search campaigns and says adding one fails with OPERATION_NOT_PERMITTED_FOR_CONTEXT. language_ids is passed through as given, so the dry run shows Google's answer; leave it out unless there is a reason to send it."
  ],
  "changes.language_ids": [
    "1000"
  ]
}
--- draft_campaign, TARGET_CPA 50, daily budget 100 (no language_ids where allowed)
{
  "warnings": [
    "Daily budget 100.00 USD is less than 5x target CPA 50.00 USD (250.00 USD/day). 5x is AdLoop's rule of thumb, not a Google requirement; Google's low-traffic troubleshooting guide suggests a daily budget of 2 to 3 times the target CPA."
  ],
  "changes.language_ids": []
}
--- update_campaign language_ids=[]
{
  "warnings": [
    "language_ids=[] removes all campaign-level language criteria. On a Search campaign Google no longer uses them (retired late September 2026). On campaigns that still take language targeting (Display, Video, App, Demand Gen with campaign-level languages, and the YouTube, Display, Discover and Gmail channels of Performance Max) removing them can widen who sees the ads."
  ],
  "changes.language_ids": []
}
--- get_campaign_performance: three converting Search campaigns, each losing 35% of impressions to budget
insights: [
  "2 converting campaign(s) lose at least 20% of Search impression share to budget: Maximize, target CPA set (35.0% lost to budget), Target CPA (35.0% lost to budget). They run out of budget while converting; compare their CPA with the account before moving budget to them.",
  "1 converting campaign(s) on Maximize conversions or Maximize conversion value without a target also report at least 20% lost to budget: Maximize, no target (35.0% lost to budget). Do not read that as room for more budget: without a target these strategies aim to spend the full daily budget, and Google says its Lost IS (budget) column is incompatible with them. Check Google's budget simulator before raising their budget."
]
budget_limited_converters: [{"name": "Maximize, target CPA set", "bidding_strategy_type": "MAXIMIZE_CONVERSIONS"}, {"name": "Target CPA", "bidding_strategy_type": "TARGET_CPA"}, {"name": "Maximize, no target", "bidding_strategy_type": "MAXIMIZE_CONVERSIONS", "budget_share_reliability": "unreliable"}]

Tests

tests/test_google_guidance_accuracy.py, 47 cases. They cover the draft previews, the mutate operations that reach Google (a create without languages sends no language criterion; given languages are passed through; an empty list on update removes and creates nothing), every target and portfolio combination for the budget insight, a campaign beyond the first five, the truncated list feeding the dashboard, and the wording in the three rule copies.

Full suite: 2421 passed, 2 skipped (was 2374 passed on main before the new file).

Two eval files asked for the old behaviour and are updated (tests/evals/write.json, tests/evals/planning.json).

Review

Before opening this I had the change audited independently (OpenAI Codex, three passes) against the Google pages above, with the instruction to try to refute it. The first pass rejected two of my own statements: I had written that Google publishes no budget multiple, and the budget-share caveat ignored targets. Both are corrected here, and the later passes are where the target, portfolio and unknown handling in section 3 comes from. The last pass re-checked every quote and found no remaining blockers. Of the 47 new test cases, 33 fail on main; the other 14 are compatibility and negative-control cases (existing language pass-through, strategies the caveat must not touch, the three rule copies matching).

Not in this PR

  • A language-only update_campaign is still annotated as a "targeting" change in the GA4 suggestion, and an empty language_ids shows as a blank value on the approval card. Cosmetic; the warning text is shown.
  • The Microsoft Advertising read has its own "lose 20%+ of impressions to budget" insight. I left it alone: the Google page is about Google's column.

- Search campaigns: language_ids is no longer required. Google retired manual
  language targeting for Search campaigns in late September 2026. When it is
  passed, the preview warns and it is sent unchanged; update_campaign accepts
  language_ids=[] to remove campaign-level language criteria.
- The '5x target CPA' budget warning no longer says 'Google recommends'. It is
  AdLoop's rule of thumb; Google's own guideline is 2 to 3 times the target CPA.
- get_campaign_performance: for Maximize conversions and Maximize conversion
  value run without a target, the budget-lost share is marked unreliable, gets
  its own insight and is left out of the dashboard's budget alert. Google says
  the Lost IS (budget) column is incompatible with those strategies.
- Rules: 'Learning' status is described as Google documents it. Budget, target,
  creative and targeting changes never trigger it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant