SpringServe macros are formatted as capital letters within double curly brackets and will be filled in by the adserver when properly implemented in multiple places: endpoint URLs of demand tags, event pixels, and landing page urls for creative asset demand.
When setting up your demand tags, the macros must be implemented correctly in order to pass the values to your demand partners. You can replace them manually or you can use the Suggested Macros tool.
Once your endpoint url has been inputted into the endpoint settings, the Suggested Macros tool will populate. SpringServe will detect the adserver and display the endpoint with supported macros replaced with SpringServe macros. Click the Copy button and paste the updated endpoint url into the Endpoint URL field. Most major adservers are included in the Suggested Macros platform list. If you are working with tags from an adserver that is unknown by the suggested macros tool, please reach out to support@springserve.com.
To check if the demand tag will return a response, you can use the Tag Validation tool. You can validate the tag As Is or you can Replace Macros. When validating As Is, SpringServe will call the tag as it appears in the Endpoint URL field. If there is targeting on the demand tag, you may need to hard code certain macros. For example, if the demand tag is targeting large players, you may want to replace the height and width values with w=1600&h=900. When you select Replace Macros, the endpoint will appear in the tag validator. Click Validate and see if there is a valid response, some error, or an empty VAST response.
Notes:
Category | Demand Tag Macros | Supply tag query parameter | Description | Example values | Requirements |
|---|---|---|---|---|---|
General | {{WIDTH}} | w= | player width | 300 | |
General | {{HEIGHT}} | h= | player height | 250 | |
Player | {{SIZE}} | size= | size of player; for use for SpotX only | S | Size is parsed into dimensions that are passed to demand tags. |
General | {{DOMAIN}} | url= | page domain | ||
General | {{URL}} | url= | page url | http://www.weather.com/weather/radar/interactive/l/1037891:5:US | This passes the full page url on the demand tag |
General | {{ENCODED_URL}} | url= | encoded page url | http%3A%2F%2Fwww.weather.com%2Fweather%2Fradar %2Finteractive%2Fl%2F1037891%3A5%3AUS | |
General | {{DOUBLE_ENCODED_URL}} | url= | double encoded page url | http%253A%252F%252Fwww.weather.com%252Fweather | |
General | {{CACHEBUSTER}} | cb= | random number to prevent caching | 3708662946268 | |
| General | {{TIMESTAMP}} | unix timestamp | 1589919931 | ||
| General | {{TIMESTAMP_MS}} | unix timestamp w/ milliseconds | 1589919931035 | ||
Mobile | {{IP}} | ip= | user ip address | 52.52.52.52 | IP address is used for geo targeting. SpringServe will detect if macro is excluded from exported supply tag. |
Mobile | {{USER_AGENT}} | ua= | user agent string | Mozilla/5.0 (iPhone; CPU iPhone OS 6_0 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A5376e Safari/8536.25 | user agent used for device and operating system. SpringServe will detect if macro is excluded from exported supply tag. |
Mobile | {{LAT}} | lat= | user latitude | 33.543682 | |
Mobile | {{LON}} | lon= | user longitude | -86.779633 | |
Mobile | {{DNT}} | dnt= | do not track | 0 or 1 | dnt 1 = true and is essentially an opt out of advertisements |
Player | {{DESCRIPTION}} | desc= | video description | ||
Player | {{IAB_CATEGORY}} | ic= | IAB Category ID of site content | IAB19 | |
Player | {{DURATION}} | dur= | video duration length in seconds | 15 | |
Player | {{MINIMUM_DURATION}} | min_dur= | minimum duration in seconds | 5 | |
Player | {{MAXIMUM_DURATION}} | max_dur= | maximum duration | 30 | |
Player | {{AUTOPLAY}} | ap= | 1 if player set to autoplay, 0 if not | 0 or 1 | |
Player | {{AD_POSITION}} | ad_pos= | position of ad | 1 | position of the ad relative to other ads on the page. ex. 1 for first, 2 for second etc |
Player | {{MUTE}} | mute= | is player muted | 1 (muted) 0 (not muted) | |
| Player | {{PLACEMENT}} | placement= | placement of video | 1 (In-Stream) 2 (In-Banner) 3 (In-Article) 4 (In-Feed) 5 (Interstitial/Slider/Floating) | see IAB documentation for further details |
| fPlayer | {{SKIPPABLE}} | skip= | player will allow video to be skipped | 0 1 | see IAB documentation for further details |
| Player | {{PRODUCTION_QUALITY}} | prodq= | content quality | 0 (unknown) 1 (Professionally Produced) 2 (Prosumer) 3 (User Generated) | see IAB documentation for further details |
General | {{DEVICE_MAKE}} | device_make= | A device Make | Samsung, Apple | |
General | {{DEVICE_MODEL}} | device_model= | A devices Model | Galaxy, F8332 | |
General | {{OPERATING_SYSTEM}} | Operating System | IOS, Android, Linux, Windows, etc. | ||
General | {{OPERATING_SYSTEM_VERSION}} | Version of Operating System | 70.0.3538.110 | ||
General | {{ISP}} | Internet service provider | comcast | ||
Mobile/CTV | {{APP_BUNDLE}} | app_bundle= | app bundle | 591560124, com.pic.photoeditor | |
Mobile/CTV | {{APP_NAME}} | app_name= | app name | photoeditor | |
Mobile/CTV | {{APP_STORE_URL}} | app_store_url= | app store URL | https://play.google.com/store/apps/details?id=com.pic.photoeditor&hl=en_US | |
Mobile/CTV | {{DEVICE_ID}} | did= | user device id for all device types | 437825ef-a4a6-4575-8b70-81630c6d76e5 | |
Event | {{AUCTION_ID}} | auction id | b1b1501f-6bf6-43e6-8199-9b514a765848 | ||
Event | {{PRICEPAID}} | pp= | price paid | 10 | For use on dynamically-priced supply |
Event | {{BID_PRICE}} | header bidding bid price | 10.5 | Only for use on impression pixels | |
Media | {{KEYWORDS}} | kwds= | keywords | ||
Media | {{MEDIA_ID}} | mid= | media id | 1234 | |
Media | {{CONTENT_ID}} | cid= | content id | 12345 | |
Media | {{ENCODED_VIDEO_TITLE}} | vt= | encoded video title | my%20video%20content | |
Media | {{VIDEO_ID}} | vid= | video id | 12345 | |
Media | {{VIDEO_URL}} | v_url | encoded video url | https%3A%2F%2Fmy_video_content.mp4 | |
GDPR | {{CONSENT}} | gdpr_consent= | A consent string passed from various Consent Management Platforms (CMP's). Also accept numeric value for CTV consent. | For all cookie based environments (non-CTV) and if user is from the EU, Springserve expects a consent string in version TCF2.0. For CTV environments we accept 0/1. | Mandatory for all European traffic for GDPR |
GDPR | {{GDPR}} | gdpr= | A flag to indicate user is in the European Union and consent applies | 1 (true, in EU) or 0 (false, non-EU, GDPR does not apply) If not present, callee should do geoIP lookup, and GDPR applies for EU IP addresses | Mandatory for all European traffic for GDPR |
| CCPA | {{US_PRIVACY}} | us_privacy= | A mandatory string for all publishers in which they must pass the privacy consent for users from California | Mandatory for all traffic from California | |
COPPA | {{COPPA}} | coppa= | A flag indicating traffic that is subject to the Children's Online Privacy Protection Act of the United States | 1 (true) or 0 (false) | This is a pass through macro that must be set by the supply partner on the top-level supply tag |
Visibility | {{MOAT_VIEW_BINARY}} | moat viewability | 1 (visible), 0 (not visible), -1 (unknown) | for use with TbV tags. Based on historical Moat data. | |
Visibility | {{IS_VISIBLE}} | is visible | 1 (visible), 0 (not visible), -1 (unknown) | for use with TbV tags. Detects visibility in real-time. | |
Detected | {{DETECTED_DOMAIN}} | domain as detected by SpringServe | detected-domain.com | ||
Detected | {{DETECTED_URL}} | url as detected by SpringServe | https://detected-domain.com | ||
Detected | {{DETECTED_ENCODED_URL}} | encoded url as detected by SpringServe | https%3A%2F%2Fdetected-domain.com | ||
Detected | {{DETECTED_DOUBLE_ENCODED_URL}} | double encoded url as detected by SpringServe | https%253A%252F%252Fdetected-domain.com | ||
Detected | {{DETECTED_HEIGHT}} | height as detected by SpringServe | 200 | ||
Detected | {{DETECTED_WIDTH}} | width as detected by SpringServe | 300 | ||
Other | {{PAY_ID}} | payid= | payment id chain | XYZ01234:ABCD56789 | Pass through macro. In OpenRTB bid requests, SpringServe will construct a payment chain which will also include this value if passed in the payid= param. |
| Other | {{SCHAIN}} | schain= | supply chain object | 1.0,1!exchange1.com,1234,1,,,!exchange2.com,abcd,1,,, | Pass through macro. Similar to pay_id/pchain, SpringServe will add any schain nodes passed in the supply tag url to the schain object in the OpenRTB bid request. |
Other | {{SS_USER_ID}} | SS specific user ID | 3319d5bb-341b-4453-b452-776487657843 | ||
Other | {{SUPPLY_TAG_ID}} | supply_tag_id | 12345 | ||
Other | {{DEMAND_TAG_ID}} | demand tag id | 65432 | ||
Other | {{ZONE_ID}} | zid= | zone id | 12345 | |
| CTV | {{DEVICE_BRAND_NAME}} | brand_name= | Connected TV brands | Samsung, Apple TV, Vizio | SpringServe will detect if macro is excluded from exported supply tag. |
| CTV Ad pod | {{CREATIVE_DURATION_MILLIS}} | Used as a demand tag macro. Will multiply CREATIVE_DURATION by 1000 | This is for demand tags that require duration in milliseconds instead of seconds | ||
| CTV Ad Pod | {{CREATIVE_DURATION}} | Used as a demand tag macro. Duration of the mediafile. | 00:00:07 | ||
| CTV Ad Pod | {{POD_MAX_DUR}} | pod_max_dur= | Used to set the maximum duration of an ad pod in seconds | 90 | Optional - if blank, the default duration is 300 seconds. Could also use the UI to create custom settings |
| CTV Ad Pod | {{POD_MAX_DUR_MILLIS}} | Used as a demand tag macro. Will multiply pod_max_dur by 1000 | 90000 | This is for demand tags that require duration in milliseconds instead of seconds | |
| CTV Ad Pod | {{POD_AD_SLOTS}} | pod_ad_slots= | used to set the minimum and maximum number of ads in a pod. Could also set the maximum and minimum | To set a maximum number of ad slots without max/min: 6 <- will return 6 ads if there are 6 ads available to fill To set a maximum number of ad slots WITH a max/min: 10-45,15-30,1-15 ← this is an example of an ad pod with 3 ad slots. Slot 1: minimum 10 seconds, maximum 45 Slot 2: minimum 15 seconds, maximum 30 Slot 3: minimum 1 seconds, maximum 15 | Optional- if blank, we will return as many ads as can fill the pod_max_dur. Could also use the UI to create custom settings |
| Content | {{CONTENT_ID}} | content_id= | id for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 24!vch192b7 | |
| Content | {{CONTENT_EPISODE}} | content_episode= | episode for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 11 | |
| Content | {{CONTENT_TITLE}} | content_title= | title for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | A%20New%20Hope | |
| Content | {{CONTENT_SERIES}} | content_series= | series for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | The%20Office | |
| Content | {{CONTENT_SEASON}} | content_season= | season for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 5 | |
| Content | {{CONTENT_GENRE}} | content_genre= | genre for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | Comedy |
If your demand partners require macros that are not supported by SpringServe, you can use passthrough macros. Passthrough macros simply look for the matching query string parameter in the ad request and fill in the value with what follows the equals sign.
append &querystring=[query_string_macro_placeholder] to your exported supply tag
include &querystring={{QP_querystring}} in the demand tag endpoint URL
For example, if you have a demand tag that requires appVersion, the endpoint URL may contain appVersion=[APPLICATION_VERSION]. SpringServe does not have a designated app version macro, but you can follow these steps to use a passthrough macro:
append &appVersion=[APPLICATION_VERSION] to your supply tag that you export to your supply partner. You will need to do this for any supply that is selling to this demand tag.
replace [APPLICATION_VERSION] in the demand tag endpoint url with {{QP_appVersion}}
SpringServe will see QP_ in the endpoint url and look for appVersion= in the request. In this case, appVersion is the query string parameter and whatever follows the equals sign will be passed through the macro. Note that your supply partner must replace [APPLICATION_VERSION] with their own supported macro in order for the value to be passed through.