Macros

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. 

Demand Tag Setup

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.

Suggested Macros

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.

Tag Validator

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.

Supported Macros & Query String Parameters

Notes:

  • In order for a field to be passed to a demand tag it must be implemented on the supply tag. 
  • All macros and query string params listed below are restricted values for Key Value targeting.

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

weather.com


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
%252Fradar%252Finteractive%252Fl%252F1037891
%253A5%253AUS


General

{{CACHEBUSTER}}

cb=

n/a

random number to prevent caching

3708662946268


General{{TIMESTAMP}} 
n/aunix timestamp1589919931
General{{TIMESTAMP_MS}}
n/aunix timestamp w/ milliseconds1589919931035

General

{{IP}}

ip=

device.ip

user ip address

52.52.52.52

IP address is used for geo targeting; we recommend passing the public IP address. SpringServe will detect if macro is excluded from exported supply tag.

General

{{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.

General

{{LAT}}

lat=

device.geo.lat

user latitude

33.543682


General

{{LON}}

lon=

device.geo.lon

user longitude

-86.779633


Privacy

{{DNT}}

dnt=

device.dnt

do not track

0 or 1

dnt 1 = true and is essentially an opt out of advertisements

General{{LIVERAMP_EIDS}}eids=user section of oRTBLiveramp envelope IDXY1000bIVBVah9ium-sZ3ykhPiXQbEcUpn4GjCtxrrw2BRDGM

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

content duration length in seconds

15


Player

{{MINIMUM_DURATION}}

min_dur=

imp.video.minduration

minimum ad duration in seconds

5


Player

{{MAXIMUM_DURATION}}

max_dur=

imp.video.maxduration

maximum ad duration in seconds

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.pos

position of ad

0 Unknown
1 Above the Fold
2 DEPRECATED - May or may not be initially visible depending on screen size/resolution.
3 Below the Fold
4 Header
5 Footer
6 Sidebar
7 Full Screen

see IAB documentation for further details

Player

{{MUTE}}

mute=

n/a

is player muted

1 (muted)
0 (not muted)

Player{{PLACEMENT}}placement=imp.video.placementplacement of video

1 (In-Stream)

2 (In-Banner)

3 (In-Article)

4  (In-Feed)

5 (Interstitial/Slider/Floating)

see IAB documentation for further details
Player{{SKIPPABLE}}skip=imp.video.skipplayer will allow video to be skipped

0

see IAB documentation for further details
Player{{PRODUCTION_QUALITY}}prodq=app.content.prodq or site.content.prodqcontent 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}}

isp=device.carrier

Internet service provider

comcast


General{{INV_PARTNER_DOMAIN}}inv_partner_domainapp.ext.inventorypartnerdomain or site.ext.inventorypartnerdomainWhen 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


Mobile/CTV{{IFA_TYPE}}ifa_type=
identifier of CTV device typerida for Roku, idfa for Apple etc

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

{{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

Privacy{{US_PRIVACY}}us_privacy=regs.ext.us_privacyA mandatory string for all publishers in which they must pass the privacy consent for users from California
Mandatory for all traffic from under US Privacy Regulation. See IAB Documentation

Privacy

{{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

Privacy{{GPP_STRING}}gpp=regs.ext.gppGlobal Privacy Policy StringDBABMA~CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAASee IAB Documentation for specification
Privacy{{GPP_SID}}gpp_sid=regs.ext.gpp_sidGlobal Privacy Policy Section ID8 (US - California section)See IAB Documentation for List

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.schainsupply chain object1.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{{SUPPLY_PARTNER_NAME}}
n/aSupply Partner NameSupply Partner A,
Other{{PUBLISHER_NAME}}
n/aPublisher NamePublisher AValue from the OpenRTB bid request
Other{{PUBLISHER_ID}}
n/aPublisher ID45678Value from the OpenRTB bid request

Other

{{DEMAND_TAG_ID}}


n/a

demand tag id

65432


Other{{DEMAND_TAG_NAME}}
n/aDemand Tag NameDemand tag A URL
Other{{DEMAND_PARTNER_NAME}}
n/aDemand PartnerDemand Partner A, Bidder A
Other{{CREATIVE_NAME}}
n/aCreative NameASPCA Puppy
Other{{CAMPAIGN_NAME}}
n/aCampaign nameShare of voice Campaign A
Other{{ZIP_CODE}}
n/aPostal code14526
Other{{METRO_CODE}}
n/aMetro COde37
Other{{STATE}}
n/aStateNY

Other

{{ZONE_ID}}

zid=

n/a

zone id

12345
CTV

{{DEVICE_BRAND_NAME}}

brand_name=n/aConnected TV brandsSamsung, Apple TV, VizioSpringServe will detect if macro is excluded from exported supply tag.
CTV Ad pod{{CREATIVE_DURATION_MILLIS}}
n/aUsed 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/aUsed as a demand tag macro.  Duration of the mediafile. 00:00:07
CTV Ad Pod{{POD_MAX_DUR}}pod_max_dur=n/aUsed to set the maximum duration of an ad pod in seconds90Optional - 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/aUsed as a demand tag macro.  Will multiply pod_max_dur by 1000 90000This is for demand tags that require duration in milliseconds instead of seconds
CTV Ad Pod{{POD_AD_SLOTS}}pod_ad_slots=n/aused 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.idid 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.episodeepisode 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.titletitle 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.seriesseries 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.seasonseason 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.genregenre 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.namename 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{{RATING}}rating=



Content{{LANGUAGE}}language=app.content.language or site.content.language


Content{{NETWORK_NAME}}network_name=



Content{{CHANNEL_NAME}}channel_name=



Content{{CONTENT_CUSTOM_1_PARAM}}

content_custom_1_param=


targets and reports on a wildcard macro. Pass in any values

age_8_10

coffee_drinker

also works for "content_custom_2_param=" and "content_custom_3_param="

Privacy

{{LMT}}lmt=
limits tracking in CTV

1 = obfuscates the user ip in outgoing requests

0 = does not obfuscate the user ip in outgoing requests


Contextual{{IRIS_CONTENT_ID}}iris_content_id=
required in query if IRIS.TV context API needs to be called by SpringserveMapping of content values from IRIS.TV
Contextual
{{IRIS_ID}}
iris_id=
IRIS.TV ID needed to support contextual targeting via IRIS.TV

Contextual{{IRIS_CONTEXT}}iris_context=
IRIS.TV context ID needed to support contextual targeting via IRIS.TV

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.

There are four types of QP macros:

  1. {{QP_querystring}} → Query Parameter → searches request URL for the query parameter value
  2. {{QPA_querystring}} → Query Parameter (Array) → searches request URL for the query parameter value, formats as an array (assuming values are comma-separated).
  3. {{QPE_querystring}} → Query Parameter (Encoded) → searches request URL for the query parameter value, url-encodes the value and escapes special characters.
  4. {{QPUNC_querystring}} → Query Parameter (Un-Encoded) → searches request URL for the query parameter value, does not url-encode value

Steps on implementing:

  1. append &querystring=[query_string_macro_placeholder] to your exported supply tag

  2. 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:

  1. 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.

  2. 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.

If you want to pass the value to your demand partner as an array you can use QPA_ instead of QP_

so if you pass in the request &key=value1,value2,value3 we would send key=[“value1”, “value2", “value3”]
You can also force the macro to populate with the unencoded value by using {{QPUNC_}}. The macro system encodes by default since macros are typically placed in demand tag urls, but this is a way to override that, particularly in the case where you want to pass a string with special characters into an RTB/Header Bidding request.