Skip to main content
The replaceMacros() function handles VAST macro substitution in tracking URLs, converting placeholder tokens like [TIMESTAMP] into actual values.

​
Function Signature

function replaceMacros(url: string, context?: MacroContext): string
​
url
string
required
URL containing VAST macros to replace
​
context
MacroContext
Values to substitute for macros

​
Supported Macros

The SDK supports 8 VAST macros as defined in the IAB specification:
MacroReplacementNotes
[TIMESTAMP]Current Unix timestampAlways replaced (e.g., 1704067200000)
[CACHEBUSTING]Random cache busterAlways replaced (e.g., x8k2j9f4p)
[ASSETURI]Media file URIURL-encoded
[CONTENTPLAYHEAD]Content positionHH:MM:SS.mmm format
[ADPLAYHEAD]Ad positionHH:MM:SS.mmm format
[ERRORCODE]VAST error codeInteger (e.g., 400)
[BREAKPOSITION]Position in breakInteger (e.g., 1)
[ADTYPE]Ad typeString (e.g., linear)
[TIMESTAMP] and [CACHEBUSTING] are always replaced, even if no context is provided.

​
Usage Examples

​
Basic Usage

import { replaceMacros } from 'adgent-sdk';

const trackingUrl = 'https://example.com/track?t=[TIMESTAMP]&cb=[CACHEBUSTING]';
const finalUrl = replaceMacros(trackingUrl);
// Result: 'https://example.com/track?t=1704067200000&cb=x8k2j9f4p'

​
With Playhead Context

const url = 'https://example.com/progress?time=[ADPLAYHEAD]';
const finalUrl = replaceMacros(url, {
  adPlayhead: 5.5
});
// Result: 'https://example.com/progress?time=00:00:05.500'

​
Error Tracking

const errorUrl = 'https://example.com/error?code=[ERRORCODE]';
const finalUrl = replaceMacros(errorUrl, {
  errorCode: 400
});
// Result: 'https://example.com/error?code=400'

​
Complete Context

const trackingUrl = 'https://example.com/track?asset=[ASSETURI]&ad=[ADPLAYHEAD]&content=[CONTENTPLAYHEAD]&type=[ADTYPE]';

const finalUrl = replaceMacros(trackingUrl, {
  assetUri: 'https://cdn.example.com/ad.mp4',
  adPlayhead: 10.25,
  contentPlayhead: 120.75,
  adType: 'linear'
});

// Result:
// 'https://example.com/track?asset=https%3A%2F%2Fcdn.example.com%2Fad.mp4&ad=00:00:10.250&content=00:02:00.750&type=linear'

​
Integration with AdTracker

The SDK’s AdTracker class automatically uses replaceMacros() internally: 
import { AdTracker } from 'adgent-sdk';

const tracker = new AdTracker({
  impressions: ['https://example.com/imp?t=[TIMESTAMP]'],
  trackingEvents: {
    start: ['https://example.com/start?pos=[ADPLAYHEAD]']
  }
});

// Macros are automatically replaced when tracking
tracker.track('start', { adPlayhead: 0 });
You don’t need to call replaceMacros() directly when using the SDK’s built-in tracking—it’s handled automatically.

​
Playhead Format

Playhead macros ([ADPLAYHEAD] and [CONTENTPLAYHEAD]) use the VAST standard format: 
HH:MM:SS.mmm
Examples:
  • 0.5 seconds → 00:00:00.500
  • 65.25 seconds → 00:01:05.250
  • 3661.123 seconds → 01:01:01.123
This format is required by the IAB VAST specification for quartile and progress tracking.

​
Types

​
VastMacro

type VastMacro =
  | '[TIMESTAMP]'
  | '[CACHEBUSTING]'
  | '[ASSETURI]'
  | '[CONTENTPLAYHEAD]'
  | '[ERRORCODE]'
  | '[BREAKPOSITION]'
  | '[ADPLAYHEAD]'
  | '[ADTYPE]';

​
MacroContext

interface MacroContext {
  assetUri?: string;
  contentPlayhead?: number;
  adPlayhead?: number;
  errorCode?: number;
  breakPosition?: number;
  adType?: string;
}

​
Implementation Details

From src/utils/macros.ts:32-87:
  • Macros are replaced using string .replace() with global regex
  • [ASSETURI] is URL-encoded using encodeURIComponent()
  • Playhead values are converted from seconds to HH:MM:SS.mmm format
  • Missing context values leave macros unreplaced
  • Replacement is idempotent (can be called multiple times safely)

​
Best Practices

Always provide context

Pass the relevant context when tracking events to ensure accurate reporting

Test with real URLs

Test macro replacement with your actual tracking URLs during development

Log for debugging

Log final URLs in development to verify macro replacement

Handle encoding

Asset URIs are automatically URL-encoded—don’t encode them manually

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us