Repository navigation
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
Conversation
- 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_idsis no longer requireddraft_campaignrejected a draft withoutlanguage_ids, and the rules said "Language targeting is mandatory".Google retired manual language targeting for Search campaigns in late September 2026:
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 updatingCampaignCriterion.languageon Search campaigns fails with aContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXTerror, though existing language criteria are still returned in queries and can be removed usingCampaignCriterionService... Stop setting language criteria when creating or updating Search campaigns."What changes:
draft_campaign:language_idsis optional (_StrListOpt = None). Geo targets stay required.language_idsis 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.create-campaigncommand 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_onlymutate that removed and re-created a language criterion on a live Search campaign was accepted without an error (two runs throughconfirm_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 avalidate_onlyexception 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_campaignandupdate_campaignwarned: "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_performanceflags 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_typeeither way. So the target has to be read.What changes:
MAXIMIZE_CONVERSIONSorMAXIMIZE_CONVERSION_VALUE, one extra query reads its target, from the campaign or from its portfolio strategy. No such campaign, no extra query.bidding_strategy_type. Entries on the two Maximize strategies getbudget_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.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-campaigncommand 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
mainand on this branch, same inputs (fake config, no account):main
this branch
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
mainbefore 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
update_campaignis still annotated as a "targeting" change in the GA4 suggestion, and an emptylanguage_idsshows as a blank value on the approval card. Cosmetic; the warning text is shown.