Version 5.0
AdvertServe User Manual :: v5.0

Macros

Introduction

What are Macros?

Macros are special tokens that can be entered into any HTML code or URL fields, which the ad server replaces with dynamic values at runtime. Some exceptions apply.

Some macros support different levels of URL encoding. Macros beginning and ending with %% are URL encoded while macros beginning and ending with $$ are not URL encoded. Only the %% variant is provided for macros with values that only contain URL safe characters.

In some situations multiple rounds of URL encoding may be required. Macros shown in blue below may have a number between 2-5 appended to their name to enable multiple rounds of encoding. For example, %%AGENT%% would be URL encoded only once while %%AGENT2%% would be URL encoded twice.

The code wizard also allows for creating custom tokens called Pass-Through Variables which allows you to extend the built-in list of tokens.

Macros

Cache Busting Macros

TokenReplaced With
%%RANDOM%% An unformatted 8-digit random number.
%%TIMESTAMP%% A timestamp in YYYYMMDDHHMMSS format.

Click Tracking Macros

TokenReplaced With
%%CLICKLINK%% A non-encoded click tracking URL which is expected to be followed by an actual target URL (landing page).
%%CLICKTAG%% A URL encoded click tracking URL which is expected to be followed by an actual target URL (landing page).
%%CRYPTCLICK%% An encrypted click tracking URL which is expected to be followed by an actual target URL (landing page).

Monetary Macros

TokenReplaced With
%%ADVCPM%% The CPM rate charged to the advertiser for the associated impression
%%ADVCPC%% The CPC rate charged to the advertiser for the associated click
%%ADVCPA%% The CPA rate charged to the advertiser for the associated action
%%PUBCPM%% The CPM rate paid to the publisher for the associated impression
%%PUBCPC%% The CPC rate paid to the publisher for the associated click
%%PUBCPA%% The CPA rate paid to the publisher for the associated action

Standard Macros

TokenReplaced With
%%AID%% The unformatted ID# of the advertiser that the displayed media belongs to.
%%ADVERTISER%% The name of the advertiser that the displayed media belongs to.
%%AGENT%% The URL encoded value of the HTTP_USER_AGENT header, which contains information about the operating system and web browser used by the visitor.
$$AGENT$$ The literal value of the HTTP_USER_AGENT header, which contains information about the operating system and web browser used by the visitor.
%%BROWSER%% The URL encoded value of the web browser name as detected from the HTTP_USER_AGENT header, which could be Chrome, Firefox, Internet Explorer, Opera, Safari, etc...
%%CID%% The unformatted ID# of the campaign that the displayed media is being displayed in. If the media is not being displayed in a campaign, this token will be replaced with a zero instead.
%%CAMPAIGN%% The name of the campaign that the displayed media is being displayed in. If the media is not being displayed in a campaign, this token will be removed.
%%CLICKID%% This value identifies both the visitor and the ID# of the media that they viewed or clicked on, which is useful to pass on to third-party tracking systems that use S2S pixels to track post-view or post-click actions. The length of this value varies between 34 and 43 alphanumeric characters. It's also not unique for every click since the same value will be generated if a visitor clicks on the same media multiple times.
%%CONTEXTUAL#%% The URL encoded value of a CSV list of the top contextual keywords for the current page. A limit of up to 10 keywords is enforced. The desired number of keywords should be specified as the number in the name of the token, such as %%CONTEXTUAL3%% or %%CONTEXTUAL5%%
%%CUSTOM1%% The URL encoded value of the custom1 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM2%% The URL encoded value of the custom2 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM3%% The URL encoded value of the custom3 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM4%% The URL encoded value of the custom4 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM5%% The URL encoded value of the custom5 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM6%% The URL encoded value of the custom6 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM7%% The URL encoded value of the custom7 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM8%% The URL encoded value of the custom8 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM9%% The URL encoded value of the custom9 parameter if provided. If this parameter is not present, this token will simply be removed.
%%CUSTOM10%% The URL encoded value of the custom10 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM1$$ The literal value of the custom1 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM2$$ The literal value of the custom2 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM3$$ The literal value of the custom3 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM4$$ The literal value of the custom4 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM5$$ The literal value of the custom5 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM6$$ The literal value of the custom6 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM7$$ The literal value of the custom7 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM8$$ The literal value of the custom8 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM9$$ The literal value of the custom9 parameter if provided. If this parameter is not present, this token will simply be removed.
$$CUSTOM10$$ The literal value of the custom10 parameter if provided. If this parameter is not present, this token will simply be removed.
%%DEVICE%% The device type of the client, which is detected from the HTTP_USER_AGENT header and will be either: desktop, tablet or mobile.
%%DNT%% The value from the DNT header, which will either be 0 or 1 and represents if the users Do Not Track settings allow tracking or not.
%%DOMAIN%% The domain name extracted from the HTTP_REFERER header, which represents the page that the displayed media was displayed on.
%%GEO_CONTINENT%% The URL encoded value of the visitors continent or Unknown if their location could not be resolved.
%%GEO_COUNTRY%% The URL encoded value of the visitors country or Unknown if their location could not be resolved.
%%GEO_COUNTRY_CODE%% The URL encoded value of the visitors country code or XX if their location could not be resolved.
%%GEO_STATE%% The URL encoded value of the visitors state/province or Unknown if their location could not be resolved.
%%GEO_CITY%% The URL encoded value of the visitors city or Unknown if their location could not be resolved.
%%GEO_POSTAL%% The URL encoded value of the visitors zip/postal code or UNKNOWN if their location could not be resolved.
%%GEO_DMA%% The URL encoded value of the visitors DMA or Unknown if their location could not be resolved.
%%GEO_DMA_CODE%% The URL encoded value of the visitors DMA code or 0 if their location could not be resolved.
%%GEO_TIMEZONE%% The URL encoded value of the visitors time zone or Unknown if their location could not be resolved.
%%GEO_LAT%% The URL encoded value of the visitors latitude or 0.00000 if their location could not be resolved.
%%GEO_LON%% The URL encoded value of the visitors longitude or 0.00000 if their location could not be resolved.
$$GEO_CONTINENT$$ The literal value of the visitors continent or Unknown if their location could not be resolved.
$$GEO_COUNTRY$$ The literal value of the visitors country or Unknown if their location could not be resolved.
$$GEO_COUNTRY_CODE$$ The literal value of the visitors country code or XX if their location could not be resolved.
$$GEO_STATE$$ The literal value of the visitors state or Unknown if their location could not be resolved.
$$GEO_CITY$$ The literal value of the visitors city or Unknown if their location could not be resolved.
$$GEO_POSTAL$$ The literal value of the visitors zip/postal code or UNKNOWN if their location could not be resolved.
$$GEO_DMA$$ The literal value of the visitors DMA or Unknown if their location could not be resolved.
$$GEO_DMA_CODE$$ The literal value of the visitors DMA code or 0 if their location could not be resolved.
$$GEO_TIMEZONE$$ The literal value of the visitors time zone or Unknown if their location could not be resolved.
$$GEO_LAT$$ The literal value of the visitors latitude or 0.00000 if their location could not be resolved.
$$GEO_LON$$ The literal value of the visitors longitude or 0.00000 if their location could not be resolved.
%%GID%% The unformatted ID# of the group that a zone belongs to.
%%GROUP%% The name of the group that a zone belongs to.
%%HUMIDITY%% The humidity in the visitors current location expressed as a percentage between 0 and 100.
%%IP%% The IP address of the visitor.
%%KEYWORDS%% The literal value, which is always URL encoded, of the keywords parameter if provided. If this parameter is not present, this token will simply be removed.
%%LANGUAGE%% The preferred language of the visitor.
%%MID%% The unformatted ID# of the displayed media.
%%MEDIA%% The name of the displayed media.
%%ORG%% The name of ISP or organization that the IP address of the visitor is registered to.
%%OS%% The URL encoded value of the operating system name as detected from the HTTP_USER_AGENT header, which could be Linux, Mac, Windows XP, Windows Vista, Windows 7, Windows 8, Windows 10, etc...
%%PID%% The unformatted ID# of the publisher serving the displayed media. If the media is not being served by a publisher, this token will be replaced with a zero instead.
%%PUBLISHER%% The name of the publisher serving the displayed media. If the media is not being served by a publisher, this token will be removed.
%%PROTOCOL%% The protocol of request, which will normally be http or https. If you have an HTML creative that you need to display on both HTTP and HTTPS pages, you can change resource file locations (CSS, GIF, JPG, etc...) to make the protocol dynamic: %%PROTOCOL%%://www.example.com/path/to/banner468x60.gif
%%REFERRER%% The URL encoded value of the HTTP_REFERER header, which represents the page that the displayed media was displayed on.
$$REFERRER$$ The literal value of the HTTP_REFERER header, which represents the page that the displayed media was displayed on.
%%RESOLUTION%% The screen resolution of the visitor (if available).
%%TEMPERATURE%% The temperature in the visitors current location expressed in Fahrenheit or zero if their location or weather data could not be resolved.
%%UUID%% The value of the AVPUID cookie, which contains a 32-character unique user ID for the visitor.
%%VEID%% The id attribute of the DOM element containing the creative that is being measured for viewability.
%%WEATHER%% The current weather condition (i.e. Sunny or Snow) in the visitors current location or Other if their location or weather data could not be resolved.
%%ZID%% The unformatted ID# of the zone that the displayed media is being displayed in. If the media is not being displayed in a zone, this token will be replaced with a zero instead.
%%ZONE%% The name of the zone that the displayed media is being displayed in. If the media is not being displayed in a zone, this token will be removed.

VAST Tag Macros

TokenReplaced With
%%VWIDTH%% The video player width in pixels.
%%VHEIGHT%% The video player height in pixels.
%%VID%% The ID of the content video that will play after the ad.
%%VFILE%% The filename of the content video that will play after the ad.
%%VTITLE%% The title of the content video that will play after the ad.
%%VDURATION%% The duration of the content video that will play after the ad.
%%VINFO%% The description of the content video that will play after the ad.

VAST Tag Macros (Mobile Apps)

TokenReplaced With
%%BUNDLE%% iOS App Bundle Identifier
%%IDFA%% Identity for Advertisers
%%APP%% App Name
%%APPSTORE%% Appstore URL
%%APPCAT%% Appstore Category
%%LAT%% GPS Latitude
%%LON%% GPS Longitude

Exceptions

External Content URLs

Dynamic media, HTML banner media and window media all include the option to load HTML content from an external URL. This feature is intended to be used to when such HTML content is dynamically generated either in real-time or periodically if caching is employed. While all macros may be used within the returned HTML content only the following macros may be used within the external URL:

If you have a situation where other macros are required to build your dynamic HTML content consider using a JavaScript or IFRAME tag instead of having the ad server load the external content directly.

VAST Tags

VAST Tag macros may only be used in third-party VAST tags and are only available when supported by your video player.

Additionally mobile VAST tag macros are only supported in native mobile apps and require the cooperation of the app to insert the macro values.