Table of Contents |
---|
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.
...
Category | Demand Tag Macros | Supply tag query parameter | OpenRTB parameter | Description | Example values | Requirements |
---|---|---|---|---|---|---|
General | {{WIDTH}} | w= | imp.video.w | player width | 300 | |
General | {{HEIGHT}} | h= | imp.video.h | player height | 250 | |
Player | {{SIZE}} | size= | n/a | size of player; for use for SpotX only | S | Size is parsed into dimensions that are passed to demand tags. |
General | {{DOMAIN}} | url= | site.domain or app.domain | page domain | ||
General | {{URL}} | url= | site.page | 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= | site.page | encoded page url | http%3A%2F%2Fwww.weather.com%2Fweather%2Fradar %2Finteractive%2Fl%2F1037891%3A5%3AUS | |
General | {{DOUBLE_ENCODED_URL}} | url= | site.page | double encoded page url | http%253A%252F%252Fwww.weather.com%252Fweather | |
General | {{CACHEBUSTER}} | cb= | n/a | random number to prevent caching | 3708662946268 | |
General | {{TIMESTAMP}} | n/a | unix timestamp | 1589919931 | ||
General | {{TIMESTAMP_MS}} | n/a | unix timestamp w/ milliseconds | 1589919931035 | ||
Mobile | {{IP}} | ip= | device.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= | device.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= | device.geo.lat | user latitude | 33.543682 | |
Mobile | {{LON}} | lon= | device.geo.lon | user longitude | -86.779633 | |
Mobile | {{DNT}} | dnt= | device.dnt | do not track | 0 or 1 | dnt 1 = true and is essentially an opt out of advertisements |
Player | {{DESCRIPTION}} | desc= | n/a | video description | ||
Player | {{IAB_CATEGORY}} | ic= | site.cat or app.cat | IAB Category ID of site content | IAB19 | |
Player | {{DURATION}} | dur= | n/a | video duration length in seconds | 15 | |
Player | {{MINIMUM_DURATION}} | min_dur= | imp.video.minduration | minimum duration in seconds | 5 | |
Player | {{MAXIMUM_DURATION}} | max_dur= | imp.video.maxduration | maximum duration | 30 | |
Player | {{AUTOPLAY}} | ap= | n/a | 1 if player set to autoplay, 0 if not | 0 or 1 | |
Player | {{AD_POSITION}} | ad_pos= | imp.video.startdelay | 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= | n/a | is player muted | 1 (muted) 0 (not muted) | |
Player | {{PLACEMENT}} | placement= | imp.video.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= | imp.video.skip | player will allow video to be skipped | 0 1 | see IAB documentation for further details |
Player | {{PRODUCTION_QUALITY}} | prodq= | app.content.prodq or site.content.prodq | content quality | 0 (unknown) 1 (Professionally Produced) 2 (Prosumer) 3 (User Generated) | see IAB documentation for further details |
General | {{DEVICE_MAKE}} | device_make= | device.make | A device Make | Samsung, Apple | |
General | {{DEVICE_MODEL}} | device_model= | device.model | A devices Model | Galaxy, F8332 | |
General | {{OPERATING_SYSTEM}} | device.os | Operating System | IOS, Android, Linux, Windows, etc. | ||
General | {{OPERATING_SYSTEM_VERSION}} | device.osv | Version of Operating System | 70.0.3538.110 | ||
General | {{ISP}} | device.carrier | Internet service provider | comcast | ||
General | {{INV_PARTNER_DOMAIN}} | inv_partner_domain | app.ext.inventorypartnerdomain or site.ext.inventorypartnerdomain | When a site or an app contains ad inventory that is owned by another partner - the app or site should list all domains for those partners via this directive. | programmerA.com | |
Mobile/CTV | {{APP_BUNDLE}} | app_bundle= | app.bundle | app bundle | 591560124, com.pic.photoeditor | |
Mobile/CTV | {{APP_NAME}} | app_name= | app.name | app name | photoeditor | |
Mobile/CTV | {{APP_STORE_URL}} | app_store_url= | app.storeurl | app store URL | https://play.google.com/store/apps/details?id=com.pic.photoeditor&hl=en_US | |
Mobile/CTV | {{DEVICE_ID}} | did= | device.ifa | user device id for all device types | 437825ef-a4a6-4575-8b70-81630c6d76e5 | |
Event | {{AUCTION_ID}} | bidrequest.id | auction id | b1b1501f-6bf6-43e6-8199-9b514a765848 | ||
Event | {{PRICEPAID}} | pp= | n/a | price paid | 10 | For use on dynamically-priced supply |
Event | {{BID_PRICE}} | n/a | header bidding bid price | 10.5 | Only for use on impression pixels | |
Media | {{KEYWORDS}} | kwds= | n/a | keywords | ||
Media | {{MEDIA_ID}} | mid= | n/a | media id | 1234 | |
Media | {{CONTENT_ID}} | cid= | app.content.id or site.content.id | content id | 12345 | |
Media | {{ENCODED_VIDEO_TITLE}} | vt= | n/a | encoded video title | my%20video%20content | |
Media | {{VIDEO_ID}} | vid= | n/a | video id | 12345 | |
Media | {{VIDEO_URL}} | v_url | n/a | encoded video url | https%3A%2F%2Fmy_video_content.mp4 | |
GDPR | {{CONSENT}} | gdpr_consent= | user.ext.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= | regs.ext.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= | regs.ext.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= | regs.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}} | n/a | moat viewability | 1 (visible), 0 (not visible), -1 (unknown) | for use with TbV tags. Based on historical Moat data. | |
Visibility | {{IS_VISIBLE}} | n/a | is visible | 1 (visible), 0 (not visible), -1 (unknown) | for use with TbV tags. Detects visibility in real-time. | |
Detected | {{DETECTED_DOMAIN}} | n/a | domain as detected by SpringServe | detected-domain.com | ||
Detected | {{DETECTED_URL}} | n/a | url as detected by SpringServe | https://detected-domain.com | ||
Detected | {{DETECTED_ENCODED_URL}} | n/a | encoded url as detected by SpringServe | https%3A%2F%2Fdetected-domain.com | ||
Detected | {{DETECTED_DOUBLE_ENCODED_URL}} | n/a | double encoded url as detected by SpringServe | https%253A%252F%252Fdetected-domain.com | ||
Detected | {{DETECTED_HEIGHT}} | n/a | height as detected by SpringServe | 200 | ||
Detected | {{DETECTED_WIDTH}} | n/a | width as detected by SpringServe | 300 | ||
Other | {{PAY_ID}} | payid= | source.pchain | 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= | source.ext.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}} | user.buyeruid | SS specific user ID | 3319d5bb-341b-4453-b452-776487657843 | ||
Other | {{SUPPLY_TAG_ID}} | imp.tagid (on the /bid endpoint) | supply_tag_id | 12345 | ||
Other | {{DEMAND_TAG_ID}} | n/a | demand tag id | 65432 | ||
Other | {{ZONE_ID}} | zid= | n/a | zone id | 12345 | |
CTV | {{DEVICE_BRAND_NAME}} | brand_name= | n/a | Connected TV brands | Samsung, Apple TV, Vizio | SpringServe will detect if macro is excluded from exported supply tag. |
CTV Ad pod | {{CREATIVE_DURATION_MILLIS}} | n/a | 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}} | n/a | Used as a demand tag macro. Duration of the mediafile. | 00:00:07 | ||
CTV Ad Pod | {{POD_MAX_DUR}} | pod_max_dur= | n/a | 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}} | n/a | 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= | n/a | 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= | app.content.id or site.content.id | id for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 24!vch192b7 | |
Content | {{CONTENT_EPISODE}} | content_episode= | app.content.episode or site.content.episode | episode for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 11 | |
Content | {{CONTENT_TITLE}} | content_title= | app.content.title or site.content.title | title for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | A%20New%20Hope | |
Content | {{CONTENT_SERIES}} | content_series= | app.content.series or site.content.series | series for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | The%20Office | |
Content | {{CONTENT_SEASON}} | content_season= | app.content.season or site.content.season | season for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | 5 | |
Content | {{CONTENT_GENRE}} | content_genre= | app.content.genre or site.content.genre | genre for "content" object for PC and SSHB bid requests (see OpenRTB 2.5) | Comedy | |
Content | {{CONTENT_PRODUCER_NAME}} | content_producer_name= | app.content.producer.name or site.content.producer.name | name for "producer" object for PC and SSHB bid request (see OpenRTB 2.5) | "Warner Bros" | |
Content | {{CONTENT_LIVESTREAM}} | content_livestream= | app.content.livestream or site.content.livestream | 0 = not live 1 = content is live (e.g., stream, live blog) | ||
Content | {{CONTENT_RATING}} | content_rating= | ||||
Content | {{CONTENT_LANGUAGE}} | content_language= | app.content.language or site.content.language | |||
Content | {{NETWORK_NAME} | network_name= | ||||
Content | {{CHANNEL_NAME}} | channel_name= |
Passthrough Macros
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.
...