Ad Macro Configuration

Learn how to configure dynamic macros (placeholders) in your ad URLs for personalized targeting and tracking.

What are Macros?

Macros are placeholders in ad URLs that get replaced with dynamic values when the ad loads. They enable:

• Personalized ad targeting
• Proper tracking and attribution
• Cache busting
• Custom parameter passing

Example:

Input:  https://ads.example.com?page=[page_url]&time=[timestamp]
Output: https://ads.example.com?page=https%3A%2F%2Fexample.com&time=1704123456789

Configuring Macros

Step 1: Navigate to Ad Settings

1. Go to Integrations → Google Ad Manager
2. Enter your Video Tag URL with placeholders

Step 2: Add Macros

You can add macros in two ways:

Option A: Auto-Detect (Recommended)

1. Click "Detect Macros" button
2. System automatically finds placeholders in your URL
3. Select values from dropdown for each macro

Option B: Manual Configuration

1. Click "Add Macro"
2. Enter Name: The placeholder name (e.g., placeholder1)
3. Enter Value: What to replace it with (see options below)

Step 3: Save Configuration

Click Save to apply your macro configuration.

Available Macro Values

Page Information

Select from these predefined values in the dropdown:

Value	Description	Example Output
[description_url]	Current page URL (encoded)	https%3A%2F%2Fexample.com
[page_url]	Same as description_url	https%3A%2F%2Fexample.com
[domain]	Current domain (encoded)	example.com
[page_title]	Page title (encoded)	My%20Page%20Title
[pathname]	URL path only (encoded)	%2Farticles%2F123
[protocol]	Protocol (http/https)	https
[referrer_url]	Referrer URL (encoded)	https%3A%2F%2Fgoogle.com

Cache Busting

Value	Description	Example Output
[timestamp]	Unique timestamp	1704123456789
[correlator]	Same as timestamp	1704123456789
[random]	Random number	847593021

Custom JavaScript Variables

For custom values from your page, use window. prefix:

Examples:

window.myApp.userId
window.userData.subscription
window.IQD_varPack.iqd_TestKW

tip

The dropdown allows custom input. Just type your window path directly!

Configuration Rules

Google Ad Manager Reserved Macros

IMPORTANT: Some parameter names are reserved by Google Ad Manager and should NOT be configured in StorifyMe macros. These must remain as placeholders so Google can replace them server-side.

Reserved macro names (DO NOT configure):

• url
• description_url
• correlator
• referrer_url
• page_url
• domain
• timestamp

If your ad tag URL has these as placeholder names (e.g., url=[placeholder2]), do not create a macro for that placeholder. Leave it unreplaced.

Example:

❌ WRONG - This will break ads:
URL: https://ads.com?url=[placeholder2]
Macro: {name: "placeholder2", value: "[description_url]"}

✅ CORRECT - Let Google handle it:
URL: https://ads.com?url=[placeholder2]
Macros: (don't configure placeholder2 at all)

See Why This Matters below for technical details.

✅ Use Brackets For Special Values

// ✅ Correct
Value: [description_url]
Value: [timestamp]
Value: [referrer_url]

❌ Don't Use Brackets For Window Objects

// ✅ Correct
Value: window.userId
Value: window.myApp.category

// ❌ Incorrect
Value: [window.userId]
Value: [window.myApp.category]

Example Configurations

Basic Setup

Video Tag URL:

https://pubads.g.doubleclick.net/gampad/ads?
  description_url=[page]&
  correlator=[cache]

Macro Configuration:

Name	Value
page	[description_url]
cache	[correlator]

Advanced Setup with Custom Variables

Video Tag URL:

https://pubads.g.doubleclick.net/gampad/ads?
  description_url=[page]&
  cust_params=kw%3D[keyword]&
  correlator=[time]

Macro Configuration:

Name	Value	Purpose
page	[description_url]	Track page URL
keyword	window.IQD_varPack.iqd_TestKW	Custom user keyword
time	[timestamp]	Cache buster

note

Make sure window.IQD_varPack.iqd_TestKW exists on your page before using it!

Debugging

Enable Debug Mode

Add this parameter to your URL:

https://your-website.com/?storifyme_debug_ads=true

View Console Logs

1. Open browser console (F12)
2. Navigate to a story with ads
3. Look for logs starting with [GoogleVideoAdManager]

Example Output:

[GoogleVideoAdManager] videoTagUrl (BEFORE): ...?page=[page]&time=[time]
[GoogleVideoAdManager] Processing macro: {name: "page", value: "[description_url]"}
[GoogleVideoAdManager] Set [description_url] to: https%3A%2F%2Fexample.com
[HELPERS.replacePlaceholders] ✓ Replacement made!
[GoogleVideoAdManager] videoTagUrl (AFTER): ...?page=https%3A%2F%2Fexample.com&time=1704123456789

Troubleshooting

Placeholder Not Replaced

Problem: [placeholder1] still shows in ad URL

Solutions:

1. Check placeholder name matches exactly (case-sensitive)
2. Verify macro is configured
3. Check debug logs for errors

Empty or Undefined Value

Problem: Macro replaced with empty string

Solutions:

1. For special values: Check brackets are included: [description_url] not description_url
2. For window objects: Verify variable exists:

   console.log(window.myApp.userId)  // Should not be undefined

Wrong Format

Common Mistakes:

Issue	Wrong	Correct
Missing brackets on special value	description_url	[description_url]
Brackets on window object	[window.userId]	window.userId
Placeholder name mismatch	URL: [page] Config: pageUrl	Both should be page

Best Practices

1. Always Use Cache Busting

Prevent ad caching by adding a timestamp:

&correlator=[timestamp]

2. Test with Debug Mode

Always test your configuration:

?storifyme_debug_ads=true

3. Verify Window Variables

Before using window.variableName, ensure it exists:

// In your page code
window.myApp = window.myApp || {};
window.myApp.userId = "user123";

4. Use Descriptive Names

// ✅ Good
{ name: "user_id", value: "window.user.id" }
{ name: "content_category", value: "window.pageData.category" }

// ❌ Confusing
{ name: "p1", value: "window.x" }
{ name: "p2", value: "window.y" }

5. Document Your Configuration

Keep a reference of what each macro does:

// Macro Documentation
// user_keyword → User targeting from window.IQD_varPack.iqd_TestKW
// page_url → Current page URL for tracking
// cache_buster → Unique timestamp to prevent caching

Integration Examples

E-commerce Site

// Page setup
window.productData = {
  category: "electronics",
  price: "499.99"
};

Macro Configuration:

Name	Value
category	window.productData.category
price	window.productData.price
page	[description_url]

News/Media Site

// Page setup
window.articleData = {
  topic: "sports",
  author: "john-doe"
};

Macro Configuration:

Name	Value
topic	window.articleData.topic
page_title	[page_title]
referrer	[referrer_url]

Common Use Cases

1. Page Tracking

description_url=[description_url]

2. Referrer Tracking

url=[referrer_url]

3. Cache Busting

correlator=[timestamp]

or

cache=[random]

4. Custom User Data

cust_params=user%3D[user_id]

Configure: user_id → window.user.id

5. Content Categorization

cust_params=category%3D[content_cat]

Configure: content_cat → window.pageData.category

Google Ad Manager Integration

Why Some Macros Should NOT Be Configured

Google Ad Manager has reserved macro names that it expects to replace server-side. When you configure these in StorifyMe, you're replacing them client-side, which prevents Google from doing its own macro replacement.

Technical Flow:

1. ❌ WRONG - StorifyMe replaces everything:
   Client: url=[placeholder2]
   → StorifyMe: url=https%3A%2F%2Fpage.com
   → Google: "This is already a value, not a macro" → AdError 1009

2. ✅ CORRECT - Let Google replace its own macros:
   Client: url=[placeholder2]
   → StorifyMe: url=%5Bplaceholder2%5D (leaves it alone)
   → Google: "This is my macro!" → url=https%3A%2F%2Fpage.com → Ads load ✓

When to Use StorifyMe Macros

Only configure macros for:

• Custom JavaScript values (window.yourApp.data)
• Custom URL parameters not used by Google
• Your own targeting keywords
• Values that are NOT Google Ad Manager reserved names

Example (Correct):

URL: https://ads.com?cust_params=kw%3D[keyword]&url=[page]&correlator=[time]

Macro Configuration:
- keyword → window.IQD_varPack.iqd_TestKW  ✅ Custom value, configure it
- page → (don't configure)                 ✅ Google macro, leave alone
- time → (don't configure)                 ✅ Google macro, leave alone

Automatic Macros

Google IMA SDK automatically populates these macros server-side:

• correlator - Random cache buster
• url - Page URL
• description_url - Description URL
• referrer_url - Referrer URL
• page_url - Page URL (alias)
• domain - Domain name
• timestamp - Timestamp
• Plus: msid, an, omid_p, pvid, sid

Do not configure these in StorifyMe - let Google handle them automatically.

API Reference

Macro Object

interface Macro {
  name: string;      // Placeholder name (without brackets)
  value: string;     // Special value (with brackets) or window path (without)
}

Example

{
  name: "page_url",           // Matches [page_url] in URL
  value: "[description_url]"  // Special value
}

Need Help?

If you encounter issues:

1. Enable debug mode:

   ?storifyme_debug_ads=true

2. Check console logs for detailed information

3. Contact support with:

   • Your video tag URL
   • Macro configuration
   • Console logs

Related Documentation

• Ads Web SDK Introduction
• Custom Ad Provider Setup