Skip to main content

Creating a Layout

A layout decides which ad slots load on which pages. Build one by picking the ad slots, scoping it to a set of URL patterns, and optionally refining by audience and GAM targeting.

What you'll accomplish

A layout that will load a defined set of ad slots on a defined set of URLs, once shipped in a release.

Before you begin​

Prerequisites

  • At least one ad slot created (Create a slot →)
  • A rough plan of the URL structure this layout should cover

Step 1: Open the new-layout page​

  1. In Ad Manager (main) mode, confirm the right domain is selected.
  2. Go to Inventory → Layouts.
  3. Click + Layout (top-right).

Type a name in the title field before moving on (it's a required field).

Step 2: Ad Slots tab — pick the slots​

The first tab is Ad Slots. Use the list manager to search existing ad slots and add them to this layout. Only slots you add here will load on pages this layout matches.

Typical article layout: article_header, article_sidebar_top, article_incontent_1, article_incontent_2, article_incontent_3.

Step 3: Scope tab — where the layout applies​

The Scope tab has two fieldsets: Page Paths and Audience.

Page Paths​

Add one or more page-path rules. Each rule has a pattern type and a path value.

Pattern typeMeaningExample pathMatches
Exact matchPath must be identical// only
Starts withPath must begin with the value/blog//blog/post-1, /blog/category/tech
ContainsValue appears anywhere in the path/news//us/news/2024/foo
Ends withPath must end with the value.amp/article/foo.amp
Regex matchRegular-expression match on the path^/article/[0-9]+$/article/12345 but not /article/foo
What's matched, what's ignored

Only the path portion of the URL is matched. Query parameters (?page=2) and hash fragments (#comments) are stripped before matching.

Regex tips (from the in-portal popover):

  • ^ = start, $ = end of path
  • . = any char, .* = any chars
  • [0-9]+ = one or more digits
  • (a|b) = matches "a" OR "b"

Audience​

Optional narrowing:

FieldWhat it does
BrowsersWhich browsers this layout applies to
DevicesWhich device categories (mobile, desktop, tablet) this layout applies to

If left empty, the layout applies to all browsers / devices.

Step 4: Targeting tab — optional key-values​

The Targeting tab carries GAM key-value pairs applied at the layout level — useful for passing page-type or section metadata into the auction at a coarser granularity than per-slot targeting.

If you don't have specific targeting needs, leave this empty.

Step 5: Save​

Click Save (Create on new layouts). The layout is created but not yet live — ship a release from Wrapper → Releases to activate it.

Quick-reference setups​

Homepage​

Name: Homepage
Ad Slots: header_billboard, sidebar_top, sidebar_bottom
Scope → Page Paths:
  pattern: Exact match    path: /

Article pages​

Name: Article Pages
Ad Slots: article_header, article_sidebar_top, article_incontent_1, article_incontent_2, article_incontent_3
Scope → Page Paths:
  pattern: Starts with    path: /article/
  pattern: Starts with    path: /blog/
  pattern: Starts with    path: /news/

Category / section pages​

Name: Category Pages
Ad Slots: header, sidebar
Scope → Page Paths:
  pattern: Starts with    path: /category/
  pattern: Starts with    path: /section/

Default fallback​

Name: Default
Ad Slots: header (minimal)
Scope → Page Paths:
  pattern: Regex match    path: .*

When more than one layout matches​

There's no priority or "winner." When a page's URL and audience match several layouts, they all apply — the wrapper combines their ad slots and merges their targeting. See Layout targeting for the full model. The short version: keep layout scopes disjoint so each page matches only the layouts you intend, and remember that a broad Regex: .* layout matches every page (its slots load site-wide).

After saving​

The layout won't affect your live site until:

  1. Review — open the layout on the view page; confirm slots, scope, and targeting
  2. Ship a release — Deploying changes →
  3. Test — load a matching URL with ?pbjs_debug=true and confirm AAM Processing <N> ad slots on page in the console. See Wrapper Debugging.

Troubleshooting​

Layout not matching​

CheckFix
Pattern type and path correct?Compare against pattern types
Query / hash in the URL?Ignored — match is on the path only
Released?Create a release after saving
Audience filters?If Audience rules are set, confirm the test browser / device is included

Unexpected or duplicate slots on a page​

Layouts stack — a page loads the slots from every matching layout. If a page shows slots you didn't expect (or the same slot twice), a broader layout's scope is also matching the URL. Check every layout whose Page Paths match, and narrow the overlapping scope. See Layout targeting.

No ads showing on a matched layout​

CheckFix
Slots in the layout?Add slots on the Ad Slots tab
Slots configured?Each slot needs sizes and at least one bidder
Released?Ship a release

Common questions​

What if no layout matches?

No ads load on that page. If you want a baseline set of slots everywhere, a broad Regex match: .* layout will match every URL — but be aware its slots then load on every page, stacking on top of any more specific layout.

Can one URL match multiple layouts?

Yes — and they all apply. The wrapper combines the slots and merges the targeting from every matching layout; there's no priority or single winner. Keep scopes disjoint unless you intend slots to stack.

How do I test my targeting?

Append ?pbjs_debug=true to a test URL on your site and reload. In DevTools → Console, filter for AAM; AAM Processing <N> ad slots on page tells you how many slots the matched layout has (0 = no match).

Next​

Layout targeting →