Ad units and key-values are the labels Ad Manager uses to know where an ad is and what's around it. Get them right and reporting, targeting and testing become easy. Get them wrong and every question takes an afternoon. Here are the basics.
What an ad unit is
An ad unit represents a place where ads can show: the slot at the top of an article, the sidebar, the sticky footer on mobile. Each one has a name, a code used in your tags, and the sizes it accepts. Ad units can sit in a hierarchy, with parent units and child units underneath.
A structure that stays readable
Keep it shallow and consistent. A pattern that works for most sites:
yoursite
yoursite/article_top
yoursite/article_mid
yoursite/sidebar_1
yoursite/mobile_sticky
- One parent per site. It makes per-site reporting simple.
- Children named by position, not by advertiser or campaign.
- Lowercase and underscores. No spaces, no clever abbreviations nobody remembers.
- Only units you actually use. Old units clutter reports and confuse everyone.
Resist creating a unit for every page or section. That's what key-values are for.
What key-values are
A key-value is a label your page sends with each ad request, such as section=sport or pagetype=article. Ad Manager can then target line items to it and report on it. Keys can be set up with predefined values, which keeps things tidy, or as free-form, which is flexible but messier.
Key-values worth having
| Key | Example values | Why |
|---|---|---|
section | news, sport, guides | See which parts of the site earn most. |
pagetype | home, article, gallery | Different pages behave differently. |
pos | top, mid, bottom | Compare positions inside the same unit. |
test | a, b | Run layout tests and compare cleanly. |
Five or six good keys beat thirty half-used ones.
Agree the keys and their allowed values with whoever builds your pages, and write them down in one place. Most key-value problems come from two developers sending the same idea in two different spellings, for example Sport on one template and sport on another. Ad Manager treats those as different values, and your reports split in two. Predefined values in Ad Manager help here, because unknown values stand out instead of quietly piling up.
Review the list every few months. Remove keys nobody uses and values that no longer exist on the site.
What not to put in key-values
- No personal information. Never send email addresses, names, phone numbers or anything that identifies a person. Google's policies prohibit passing personally identifiable information to it, and it's a privacy problem anyway.
- No full URLs or search terms that might contain personal data.
- No values that change on every page view, such as timestamps. They make reports useless.
Sizes and slots
Each ad unit lists the sizes it can show. Allowing more sizes increases competition, because more buyers can bid. Allowing sizes that don't fit your layout causes the opposite problem: ads that overflow, shift the page or look broken.
- Match the sizes to the space. A sidebar slot that's 300 pixels wide should accept 300-wide sizes, not 728-wide leaderboards.
- Use size mapping for mobile. Most sites need different sizes on phones than on desktops. Define them per screen width rather than creating separate units for each device.
- Reserve the space. Give each slot a minimum height in your page CSS so content doesn't jump when the ad loads. That protects your layout and your Core Web Vitals; see ads and Core Web Vitals.
- Lazy-load lower slots. Requesting ads only when a slot is about to come into view usually helps viewability and page speed.
Putting them to work
With clean units and keys you can answer real questions quickly: which section has the best RPM, whether the mid-article slot is worth keeping, whether a new layout helped. They also make problems visible. If revenue drops, you can see whether it dropped everywhere or in one place, which is half of diagnosing a revenue drop. For where to place slots in the first place, see ad layout best practices and the viewability guide.
Talk to us about joining Bidora MCM. We send Manage Account invitations, you choose our share starting at 8%, and IVT Shield is included. Start on the Get started page or email partnership@bidora.one.