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 Add 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
Include browsersWhich browsers this layout applies to
Include 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: .*

How layout priority works​

See Layout priorities for how multiple matching layouts are resolved. The short version: give specific layouts higher priority than broad fallbacks, so the more specific one wins.

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

Wrong layout matching​

A more specific layout may be losing to a broader one due to priority order. See Layout priorities.

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. Add a default layout with a broad pattern (e.g. Regex match: .*) at low priority as a safety net.

Can one URL match multiple layouts?

Yes — but only the highest-priority match wins. Use priority to make specific layouts outrank fallbacks.

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 →