Unified Ad Server Macros

Document created by catherine.racette on Mar 21, 2018Last modified by catherine.racette on May 9, 2018
Version 9Show Document
  • View in full screen mode

Macros are short pieces of code that the ad server interprets and expands into larger pieces of code. They are a means of passing information to the third-party script/creative information such as a click tracking URL, default URL, random number for cache bursting, user information such as age, gender, keywords, etc. These can all be passed using macros.

 

After being processed by the ad server, all macros used will be replaced with the corresponding values.

Note: UAS will replace all listed macros if present in the response creative. It is applicable for all creatives either direct or third-party (Received from PubMatic SSP). 

    

Standard Macros

MacroDescription
%%AD_UNIT_ID%% Replaced with Ad Unit ID where the ad is served.
%%PROTOCOL%%Replaced with the security scheme of Ad Request. (http: / https:)
%%AD_UNIT_URL%%Replaced with URL of the Ad Unit where the ad is served.
%%AD_UNIT_URL_ESC%%Replaced with escaped URL of the Ad Unit where the ad is served.
%%USERAGENT%%Replaced with user agent received in ad request
%%TIMEZONE%%Replaced with  user or browser timezone from which ad request is made. It is an offset [+/-]hh.mm.
%%UDID%%

Replaced with Unique Device Identifier. Supporting only by the following: 

  • iOS request : IDFA in RAW format
  • Android request : Android Advertising ID in RAW format

Note: In order to replace UDID in the macro, the publisher must pass udidtype=1 or 9 and udidhash=1.

Please refer to Mobile Application-Specific Parameters

 

GDPR: If the user has not provided consent (opt-out) to PubMatic, PubMatic will replace this with an empty string in the macro. PubMatic can only replace the macro in the case of an opt-in or non-GDPR regulated inventory (Except in the EU region). 

               
%%ADVERTISER_ID%%Replaced with Advertiser Id.
%%ORDER_ID%%Replaced with winning Order Id.
%%CR_ID%%Replaced with winning Creative Id.
%%WIDTH%%Replaced with Width of the Creative
%%HEIGHT%%Replaced with Height of the Creative
%%IS_IFRAME%%Replaced with whether the ad is to be rendered in iFrame.
%%TRACKPIXEL%%Replaced with the 1x1 image pixel tracker.
%%TRACKURL%%Replaced with the pixel tracking URL.
%%CLICK_THRU_URL%%Replaced with Landing Page URL
%%CLICK_TRACK_URL%%Replaced with an link for tracking the click back to the destination URL.
%%CLICK_TRACK_URL_ESC%%Replaced with an encoded link for tracking the click back to the destination URL.
%%RANDOM%%Replaced with a random number.
%%COUNTRY_CODE%%Replaced with a country code extracted from ad call or auto detected by IP. The value will be in  in ISO-3166-1-alpha-3 format. 
%%REGION_CODE%%Replaced with a region code (a state code in case of US) or auto detected by IP.  The value will be in  in ISO-3166-1-alpha-2 format. 
%%DMA%% Replaced with dma (metro) code as entered in the ad call using ‘dma’ parameter.
%%POSTAL_CODE%%Replaced with postal code as entered in the ad call.
%%LATITUDE%%

Replaced Latitude Value only if received loc=latitude,longitude value in UAS Ad request, else not.

GDPR: PubMatic will mask the LATITUDE values up to two decimal points, e.g., 73.26 if PubMatic has no consent (opt-out) from the user. 

       
%%LONGITUDE%%

Replaced Longitude Value only if received loc=latitude,longitude value in UAS Ad request, else not.

GDPR: PubMatic will mask the LONGITUDE values up to two decimal points, e.g., -23.75 if PubMatic has no consent (opt-out) from the user. 

       
%%LOC_SOURCE%%Replaced with an integer value reflecting the source the user location is defined. Possible values are 0-Unknown, 1-GPS/Location Services 2-IP Address, 3-User provided
%%DEVICE_MAKE_ESC%%Replaced with the corresponding encoded device manufacturer name.
%%IS_SECURE%%Replaced with whether or not request is SSL-Compatibility 0(Non-Secured) or 1(Secured).
%%LI_ID%%Replaced with winning Line Item Id.
%%GDPR%%

Replaced with GDPR value only if received in ad request. This will be used to signal whether or not the request is subject to GDPR regulations.

If you are using %%UDID%%, %%LATITUDE%%, %%LONGITUDE%% or Custom Macros, they may contain user-specific information. PubMatic recommends using the %%GDPR%% and %%GDPR_CONSENT%% as well with your vendor/partner to avoid any compliance issues. 

       

%%GDPR_CONSENT%%

Replaced with base64 encoded user consent string (GDPR) for user if received in the ad request. 

If you are using %%UDID%%, %%LATITUDE%%, %%LONGITUDE%% or Custom Macros., they may contain user-specific information. PubMatic recommends using the %%GDPR%% and %%GDPR_CONSENT%% as well with your vendor/partner to avoid any compliance issues. 

       

 

Custom Macros

Unified Ad Server allows users to set custom macros. These macros start with %%VAR_<custom key name> and UAS will replace it with the same value found in the ad request for given key. Custom macros can be selected from the Custom Macro section of the macro selection. 

Important Note: UAS checks for the exact same key during macro replacement and it is case sensitive.           

    

GDPR: The custom-key macros must not be used to pass data that PubMatic or others could use or recognize as personally-identifiable information or personal data. 

    

 

Attachments

    Outcomes