---
name: set-up-keyword-level-ad-customizers
description: >-
  Gives one responsive search ad per-keyword text control, singular versus plural, with or without a descriptor,
  full phrase versus short form, so you can merge many small ad groups into one consolidated group without the
  ad relevance rating suffering. Use it when quality diagnostics show relevance slipping after consolidation, or
  when standard keyword insertion is too crude because the raw keyword reads badly in copy. This is an advanced
  maintenance-heavy tactic: skip it for low-volume or brand-only ad groups where hand-written copy is cheaper,
  skip it when the need is live prices or promotions (that is set-up-dynamic-ad-customizers), and go to
  write-compelling-rsas if the underlying ad has not been composed yet.
---
# Keyword-Level Ad Customizers for Relevance Without Fragmentation

## Purpose
Lets a single RSA speak the exact language of each keyword it serves against. You define text attributes,
assign a value per keyword (the plural form, the phrase with its descriptor, the properly cased variant), and
reference those attributes in the ad. The payoff is aggressive ad-group consolidation, better data density,
less structure to maintain, without the relevance penalty that normally comes with it.

## When to run
- A consolidated ad group covers keyword variants (singular/plural, modifiers, synonyms) that plain
  keyword insertion renders awkwardly.
- Ad relevance is rated below average despite reasonably tight theming, and splitting ad groups is the
  alternative you are trying to avoid.
- You are planning a consolidation and want to keep per-keyword messaging fidelity through the merge.

## When NOT to run
- The dynamic values are prices, stock, or promo text, run `set-up-dynamic-ad-customizers` instead.
- The RSA itself needs composing or a rewrite, run `write-compelling-rsas` first.
- The ad group is small or brand-only: assigning and maintaining per-keyword values costs more than just
  writing the copy by hand.
- Nobody will maintain values when keywords are added later, unmaintained setups quietly degrade to
  all-defaults and the effort is wasted.
- Campaign and ad-group names are unstable: feed-style targeting matches on exact names, so renames
  silently break value delivery.

## Prerequisites
- Editor access to the account (the attribute and value entry happens in the Google Ads UI).
- The target ad group's full keyword list.
- A commitment (noted with the user) that new keywords will get values assigned at creation time.

## Procedure
1. **Inventory the keywords.** Call `gads_list_keywords` for the target ad group. Group the keywords by
   surface pattern: which are singular vs plural, which carry a descriptor (material, urgency, style), which
   share a core noun.
2. **Design the attribute set.** Start with four Text-type attributes covering the core noun in singular and
   plural form, plus the complete phrase in singular and plural form. Add one vertical-specific attribute
   (a material, a modifier, a service descriptor) only if the keyword patterns from step 1 demand it. Map
   every keyword to its values in a working table before touching the UI, values render exactly as typed,
   so set the casing you want to appear in the ad.
3. **HUMAN STEP (outside VigilDog): create the attributes.** In the Google Ads business data section, create
   each attribute as Text and leave the account-level value empty, with this technique the fallback lives in
   the ad's placeholder syntax, not on the attribute.
4. **HUMAN STEP (outside VigilDog): assign per-keyword values.** In the keywords view, expose the customizer
   attribute columns and enter a custom value per keyword from the step-2 table. Work one attribute column
   across all keywords before starting the next, it is faster and catches gaps.
5. **Draft the customizer-bearing copy.** Use `gads_generate_rsa_copy` to produce headlines and
   descriptions embedding `{CUSTOMIZER.AttributeName:default}` placeholders. Attribute names in the
   syntax are case-sensitive and must match step 3 exactly. Every default must be a complete, natural
   phrase, any keyword you missed in step 4 will serve it.
6. **Deploy through the RSA skill.** Hand the approved copy to the `write-compelling-rsas` procedure (or,
   for an existing ad, its update path). As with any VigilDog write: preview first with validate_only, apply only
   after explicit user approval. If this is the session's first Google Ads write, consult
   `gads_policy_guardrail` before it.
7. **HUMAN STEP (outside VigilDog): render check.** In Ad Preview and Diagnosis, test 5–10 keywords from the
   list. Assigned values must render; defaults should appear only where you deliberately left gaps.
8. **Monitor the relevance payoff.** Over the next 7–14 days, check `gads_get_ad_strength` for the ad and
   `gads_get_rsa_asset_performance` for asset-level serving data. The goal is ad relevance holding at
   average-or-better while the consolidated group accumulates data.
9. **Maintain.** Whenever keywords are added to the group, repeat steps 2 and 4 for them immediately, `gads_list_keywords` run periodically will reveal keywords that predate their values (they will have been
   serving defaults).

## Decision rules
- **Keyword insertion vs customizers:** if the raw keyword text already reads well inside the copy, standard
  keyword insertion is simpler, use it. Use customizers only when you need to control the *form* of what
  gets inserted.
- **Coverage expectation:** every keyword without an assigned value serves the default. Partial coverage is
  acceptable only if the defaults are genuinely good copy.
- **Match types:** values attach to the keyword text, not the match type. Duplicate keywords across match
  types each need their value set.
- **Value not rendering?** Check in this order: attribute name casing in the ad syntax, whether the previewed
  keyword actually has a value, and whether the substituted text overflows the character limit (overflow
  forces the default).
- **Scale threshold:** below roughly 10 keywords in the group, hand-written static copy is usually faster and
  safer than this whole apparatus.
- **Attribute count discipline:** the four core form attributes cover the large majority of cases. Each extra
  attribute multiplies the per-keyword maintenance cost, add a fifth only when the step-1 patterns clearly
  demand it, and stop there.
- **Consolidation payoff check:** after merging ad groups on the strength of this technique, compare the
  consolidated group's ad relevance rating and data density against the pre-merge state at the 14-day mark.
  If relevance dropped despite full value coverage, the merged keywords differ in intent, not just wording, split them back out.

## Common failure modes
- **Default-flooding.** Values were assigned to most keywords at launch, but months of new keywords were
  never covered, so a growing share of impressions serve generic defaults. Bake value assignment into the
  keyword-adding routine and audit with `gads_list_keywords` monthly.
- **Casing surprises.** Values were typed lowercase and render lowercase mid-headline. Enter values in
  final display casing.
- **Rename breakage.** A campaign or ad group was renamed and name-scoped values stopped applying,
  with no error anywhere. Re-verify after any restructure.
- **Grammar traps in defaults.** A default written for one headline slot gets reused in a slot where it breaks
  the sentence. Review the ad with every placeholder replaced by its default before approving.
- **Using this where splitting was right.** If a keyword set genuinely needs a different offer or landing page,
  it needs its own ad group, customizers only solve wording, not intent mismatch.
- **Over-engineering a small group.** Ten attributes were designed for a group of eight keywords; the setup
  took longer than a year of manual edits would have. Match apparatus to keyword volume.
- **Skipping the render check.** The copy shipped straight after value entry, and a typo in one attribute name
  meant every impression served defaults for a month. The preview pass in step 7 is not optional.

## Documentation
Keep the keyword-to-value map from step 2 in the account notes and update it whenever values change. It is
the only human-readable record of what each keyword renders, and the first thing to consult when a preview
shows an unexpected default.

## Related skills
- `write-compelling-rsas`, composes and deploys the ad that carries these placeholders.
- `set-up-dynamic-ad-customizers`, the price/stock/promo counterpart; both can run in one account.
- `improve-ad-relevance`, run first to confirm relevance is actually the problem worth this effort.
- `rsa-testing-with-the-iteration-loop`, downstream testing cadence once the RSA is live and stable.