Creating a Custom Dimension

Add a new dimension to track additional data in your reports.

---

Before you begin

Plan your dimension:

• What do you want to analyze?
• What values will you track?
• Who will implement on your site?

---

Step-by-step

Step 1: Navigate to custom dimensions

1. Go to Setup → Custom Dimensions
2. Click Add Custom Dimension

Screenshot pending

The custom dimension form's exact layout is being captured for these docs. The fields below are accurate; the on-screen order and grouping may differ slightly.

Step 2: Define the dimension

Field	Description	Example
Key Name	The identifier used in code and in your site's wrapper calls	content_tier
Name	Human-readable label shown in the portal and reports	Content Tier
Description	What this dimension tracks	Content paywall tier

The Key Name must start with a lowercase letter and use only lowercase letters, numbers, and underscores.

Step 3: Choose a value type

Pick a Value Type for the dimension:

• String — free-form text; set a max length (up to 1000 characters). Filter-only in analytics.
• Enum — a fixed list of allowed values you enter. Groupable in analytics.
• Boolean — true / false. Groupable in analytics.
• Number — numeric values. Filter-only in analytics.

For Enum, add each allowed value to the list.

Step 4: Choose destinations and value source

• Destinations — turn on where the value is sent: Send to GAM (ad-server key-value), Send to Bidders (auction enrichment), and/or Send to Analytics (reporting). At least one is required.
• Value Source — how the value is provided at runtime: Static (a fixed value), Page Variable (read from a variable on the page), or Runtime API (set via the wrapper API, as shown below).

Step 5: Save

Click Save. The dimension is now created but not yet collecting data until your site starts passing values.

---

Naming guidelines

Rule	Good	Bad
Use lowercase	content_type	ContentType, CONTENT_TYPE
Use underscores	article_author	article-author, articleAuthor
Be descriptive	subscriber_status	ss, status
Keep it short	subscriber_status	the_type_of_content_on_this_page

---

Implementing on your site

After creating the dimension, your site must pass values via the wrapper API. The wrapper exposes a command queue (window.wrapperTag.cmd) and a setPageDimensions(values) method — use the queue to set values before the wrapper finishes bootstrapping:

Basic implementation

// Set before or during wrapper initialization
window.wrapperTag = window.wrapperTag || {};
wrapperTag.cmd = wrapperTag.cmd || [];
wrapperTag.cmd.push(function () {
  wrapperTag.setPageDimensions({
    content_type: 'article',
    author: 'john-smith',
    subscriber_status: 'premium',
  });
});

Values passed in a command-queue callback are applied as soon as the wrapper has bootstrapped, before the first auction.

Dynamic implementation

window.wrapperTag = window.wrapperTag || {};
wrapperTag.cmd = wrapperTag.cmd || [];
wrapperTag.cmd.push(function () {
  wrapperTag.setPageDimensions({
    content_type: document.body.dataset.contentType || 'unknown',
    author: document.querySelector('meta[name="author"]')?.content || 'unknown',
  });
});

Per-slot dimensions

If a dimension should apply only to a specific slot rather than the whole page, use setSlotDimensions(slotDivId, values):

wrapperTag.cmd.push(function () {
  wrapperTag.setSlotDimensions('ad-slot-AT-my-anchor', {
    section: 'sports',
  });
});

WordPress example

<?php /* theme header.php */ ?>
<script>
  window.wrapperTag = window.wrapperTag || {};
  wrapperTag.cmd = wrapperTag.cmd || [];
  wrapperTag.cmd.push(function () {
    wrapperTag.setPageDimensions({
      content_type: '<?php echo get_post_type(); ?>',
      author: '<?php echo get_the_author_meta("nicename"); ?>',
      category: '<?php echo get_the_category()[0]->slug ?? "uncategorized"; ?>',
    });
  });
</script>

Use the command queue

Calling wrapperTag.setPageDimensions(...) directly before the library has loaded will throw — wrapperTag may not be defined yet, or the method may not exist. Always push the call onto wrapperTag.cmd so the wrapper executes it once ready.

---

Verifying data

After implementing:

1. Allow up to an hour for data to appear in reports
2. Go to Dashboard → Monetization
3. Add your dimension as a filter or breakdown
4. Verify values appear correctly

Debugging

In the browser console (with ?pbjs_debug=true on the URL to see wrapper logs):

// Current effective values for the page
window.wrapperTag.getDimensions();

// Current effective values for a specific slot
window.wrapperTag.getDimensions('ad-slot-AT-my-anchor');

---

Troubleshooting

Dimension not appearing in reports

Cause	Solution
Just created	Allow up to an hour
Not implemented	Add code to your site
Code after wrapper	Move code before wrapper
Wrong format	Check name matches exactly

Wrong values appearing

Issue	Solution
"undefined"	Value not set correctly
"unknown"	Fallback triggered, check logic
Unexpected values	Verify predefined list or check site code

Predefined value rejected

If using predefined values, only exact matches work:

• Case-sensitive (Article ≠ article)
• No extra spaces
• Exact spelling

---

Best practices

Do

• Start with 2-3 dimensions, add more as needed
• Use consistent values across your site
• Document dimensions for your team
• Test implementation before relying on data

Don't

• Create too many dimensions (harder to manage)
• Use PII (names, emails) as values
• Change dimension names after collecting data
• Leave values undefined on pages

---

Next steps

• Custom dimensions overview →
• Continue setup →