A key-value pair takes about thirty seconds to create in Google Ad Manager and can decide whether an impression clears at floor price or attracts a premium bid. The mechanism is simple: a named attribute rides along with every ad request, and line items, deals, and demand partners read it to price the impression. The hard part is not the mechanism. It is schema design, disciplined implementation in GPT and Prebid, and reporting that proves each key earns its place. This guide walks the full path, from the first key you define to the reporting cuts that justify keeping it.
What key-values actually do in Google Ad Manager
A key-value is a named attribute attached to an ad request: the key names the attribute, and the value states what it equals. A request from a sports article might carry section=sports, pos=atf, and audience=sports_fan. Google's documentation on how to get started with key-values defines them as the mechanism for custom targeting, and every key-value you register travels with the ad calls your pages make. Two things happen downstream. Line items and deals in GAM can target those pairs, so they only deliver on impressions that match. Reporting can also slice delivery and revenue by those pairs, which turns them into an analytics layer you control end to end.
GAM distinguishes free-form keys from predefined keys. A free-form key accepts any value at request time, which launches fast but produces messy reports and typo-driven mismatches between what the page sends and what the line item expects. A predefined key carries a fixed list of values you curate in the admin, and the page simply selects from that list. Predefined keys cost more setup time and pay it back in targeting accuracy and report readability. GAM caps key names at 20 characters and values at 40 characters, and predefined keys hold a limited number of values each, so enumeration is a design constraint, not an afterthought.
One more distinction matters before you build anything: targeting keys versus reporting-only keys. A targeting key drives delivery, because line items and deals match against it. A reporting-only key travels in the request but no line item targets it, so it measures your inventory honestly without changing what delivers. Decide this role for every key at creation time, because a key that both targets and reports on the same dimension tells you what your targeting did, not what your inventory is worth.
Design the schema before you create a single key
Most key-value programs fail at the first step because teams create keys reactively, one campaign at a time, until nobody remembers what half of them mean. Start with an inventory of the signals that genuinely change what an impression is worth. For a typical publisher, that list looks like this:
- Content section or vertical: section=news, section=finance, section=sports
- Template position: pos=atf, pos=btf, pos=sticky
- Page type: pagetype=article, pagetype=category, pagetype=home
- Content topic or intent: topic=ev, intent=compare, topic=reviews
- Audience segment membership: aud=auto_intender, aud=travel_planner
- Placement tier: tier=premium, tier=standard
Then impose rules before anyone opens the GAM admin. Keys use lowercase snake_case, singular names, and verbs that describe the attribute, never the campaign. Values use lowercase with underscores, no spaces, no mixed casing, because GAM treats Sports and sports as different values and every mismatch silently kills delivery. Keep cardinality low: never pass article IDs, session IDs, or timestamps as key-values, since reports only break down a limited set of values per key and high-cardinality keys produce noise instead of insight.
Skip keys that duplicate dimensions GAM already captures natively. Device, country, browser, and ad size all appear in standard reports without any work on your side, so a key like device=mobile adds clutter, not signal. The exception proves the rule: a derived dimension such as pos=atf does add information, because GAM does not know where a slot sits on the page unless you tell it. Finally, document the intended use of each key in a shared registry before implementation, including its owner, its value list, and whether it targets, reports, or both. Teams that skip the registry end up with three keys for the same concept and no way to reconcile their reports.
Implementation in GPT: page level and slot level
The Google Publisher Tag sends key-values at two levels, and the difference trips up even experienced ad ops teams. Calling googletag.pubads().setTargeting('section', 'sports') sets a page-level pair that applies to every slot on the page. Calling slot.setTargeting('pos', 'atf') sets a slot-level pair for one ad unit only. The GPT key-value targeting guide documents both levels and the precedence rule: when the same key appears at both, the slot-level value wins for that slot. That override behavior is a feature when you use it deliberately, and a bug source when you do not.
Use page level for page-wide truth and slot level for placement truth. Section, page type, and audience segments belong at page level, because they describe the same user and page for every slot. Position, tier, and format belong at slot level, because two slots on the same page can differ. Pull values from your CMS or dataLayer rather than hardcoding them into template copies, since a hardcoded value survives a redesign and then lies about the page. One sports template with section=finance inherited from a copy-paste will poison a week of reports before anyone notices.
Validate the implementation before you negotiate anything against it. GPT's console and your browser's network tab show exactly which pairs each request carries, and GAM's delivery tools show what the ad server received. Check three things on a sample of templates: the key exists, the value matches the registry spelling, and no undefined or empty strings ride along. The string "undefined" as a value is the single most common defect we see, and it happens whenever code reads a missing dataLayer field and sends the result anyway.
Prebid and OpenRTB: making key-values visible to buyers
Header bidding made key-values more valuable, not less. Prebid's own winning-bid keys, hb_pb and hb_bidder and their companions, are key-values: the auction writes them into the GAM request so the matching line item can deliver the winning creative. That is the exact pattern to extend. Your contextual and audience key-values can also travel into bid requests, because Prebid passes first-party data through ortb2 and per-bidder parameters, so exchanges and DSPs can read your segments and adjust bids accordingly. Buyers who want guaranteed access to a segment buy it through deals: you map a deal ID to a key-value pair in GAM, and the agency targets the deal instead of hoping open market demand notices the signal.
At WireAds we combine Prebid, OpenRTB, Google MCM, Google AdX demand and direct deals from global and local brand agencies, all bidding into one auction for your inventory. Clean, consistent key-values make that stack work harder in two directions. Open market bidders price the impression more accurately because the context reaches them, and agency deals can target section, audience, or intent precisely, which is what justifies negotiated CPMs above open market rates. Sloppy values break that chain silently: the buyer never sees the signal you promised, and the deal underdelivers while everyone argues about whose fault it is.
The practical requirement is simple but strict. Whatever key-values you commit to a deal must reach every request from the placements the deal covers, with identical casing and spelling, on every template and every device. A deal targeting section=finance that misses the mobile article template delivers half its goal and the agency remembers it at renewal time.
Targeting line items, deals, and audience segments
Inside GAM, key-values do their work in the line item targeting panel. A sponsorship line item can target section=sports AND pos=atf to own the top slot on every sports page, while a standard line item with a fixed CPM competes only where its key-value criteria match. The targeting logic supports AND across keys and OR within values, so one line item can target topic=ev OR topic=hybrid while also requiring tier=premium. Keep combinations legible: if a line item needs five keys to describe where it should run, your schema probably lacks a derived key that would capture the same concept in one pair.
Audience segments earn their own treatment because they price differently from context. A contextual key like section=finance describes the page, while a segment key like aud=auto_intender describes the person, and agencies pay different premiums for each. Our Audience Encore first-party data program builds those segment keys from your own audience data and pushes them into the same targeting framework, so a direct deal can buy your intenders without any new plumbing on your side. Segment keys follow the same rules as the rest: enumerated values, documented in the registry, and validated in the request before anyone sells against them.
Placement tier keys connect targeting to creative quality. When you mark a placement tier=premium, pair that commitment with formats that justify it, and our ad format library covers the high-impact options, from interstitials to rich media, that agencies expect at that tier. A premium key on a standard 300x250 oversells the placement and disappoints the buyer at the first campaign review.
Reporting cuts that make key-values earn their keep
A key-value only justifies its existence when a report uses it, so plan the cuts before you build the keys. The core move: run your revenue report with key-values as dimensions and compare CPM by value. If section=finance clears meaningfully above section=news on comparable formats and positions, you have the evidence to negotiate section-specific deals or set section-level floors. If pos=atf shows the viewability advantage you assumed, the position key pays for itself in every floor conversation you will ever have.
Reporting-only keys deserve special mention because they answer the self-fulfilling prophecy problem. When a line item targets a key and you report on the same key, the report shows what your targeting did, which is circular. A reporting-only copy of the same signal, with no line item attached, shows what the inventory actually delivers. Publishers who skip this step end up believing their audience segments command premiums, because the only deals running against those segments are the ones priced to target them.
Our publisher analytics surfaces these cuts directly, so you can break revenue down by key-value alongside format, geo, and device without exporting GAM reports into a spreadsheet every Monday. Whatever tool you use, schedule the comparison weekly. A key-value whose CPM gap closes or inverts over a quarter stops being a sales point, and knowing that early beats defending it in a deal negotiation after the fact.
Governance: naming, ownership, and cleanup
Key-values decay without governance, because every campaign manager, every agency request, and every template refactor adds pressure to create "just one more key." Three practices hold the line. First, the registry is authoritative: a key that does not appear in the registry does not ship, and the registry records the owner, the value list, the role, and the date of the last review. Second, every key has a named owner who answers for its accuracy, because keys owned by "the team" end up owned by nobody. Third, run a quarterly review that asks one question per key: which report or which deal used this in the last quarter? Keys with no answer get deprecated, not deleted, since GAM keeps their history and a deletion can break a paused line item you forgot about.
Privacy rules bind key-values the same way they bind any other data channel. Never pass emails, names, hashed identifiers, or precise location as key-values, regardless of what an agency requests, because key-values land in logs and reports that far outlive the campaign. Under TCF and regulations like Global Privacy Control signals, audience segments derived from consented data are fine, and segments derived from tracking without a consent basis are not. The registry should record the data source for every audience key, so the compliance answer exists before the question arrives.
Failure modes we see most often
After enough audits, the same defects repeat. Check your setup against this list before your buyers find the problems for you:
- Mixed casing or trailing whitespace in values, so the page sends Sports and the line item targets sports.
- Slot-level values that unexpectedly override page-level ones after a template refactor.
- Free-text values where enumerated values belong, producing a report with forty spellings of the same concept.
- Keys that duplicate native GAM dimensions and dilute the schema.
- Keys created for one campaign, never targeted again, still riding in every request.
- Values that arrive as the string "undefined" when a dataLayer field goes missing.
- Audience keys with no documented data source, which fails the first compliance review.
None of these require deep engineering to fix. All of them require someone to own the schema, which is the actual point of governance.
A rollout sequence that works
Sequence matters, because keys sold before they validate create deals that underdeliver. Audit first: inventory every key that already exists in GAM and every value your pages currently send, and reconcile the two lists, because they almost never match. Design second: build the registry, decide roles, and get the naming rules written down. Implement third: push values from the CMS through GPT at the correct level, and validate the request on every template and device. Then, and only then, negotiate: offer the validated segments to demand partners and agencies as deal-targetable inventory. Report weekly from day one, review the registry quarterly, and deprecate without sentiment.
We run this playbook with publishers across every country where Google monetization operates, on web, app, and CTV/OTT, CPM-based with Net 30 payment. The publishers who get the most from it treat key-values as product, not plumbing: a documented, validated, reported set of signals that agencies can buy with confidence. Build the schema that way and the targeting follows.
