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/a	unix timestamp	1589919931
General	{{TIMESTAMP_MS}}		n/a	unix timestamp w/ milliseconds	1589919931035
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 oRTB	Liveramp envelope ID	XY1000bIVBVah9ium-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.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
Player	{{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}}	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
Mobile/CTV	{{IFA_TYPE}}	ifa_type=		identifier of CTV device type	rida 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.	If user is from the EU, Springserve expects a consent string in version TCF2.0.	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_privacy	A 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.gpp	Global Privacy Policy String	DBABMA~CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA	See IAB Documentation for specification
Privacy	{{GPP_SID}}	gpp_sid=	regs.ext.gpp_sid	Global Privacy Policy Section ID	8 (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.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	{{SUPPLY_PARTNER_NAME}}		n/a	Supply Partner Name	Supply Partner A,
Other	{{PUBLISHER_NAME}}		n/a	Publisher Name	Publisher A	Value from the OpenRTB bid request
Other	{{PUBLISHER_ID}}		n/a	Publisher ID	45678	Value from the OpenRTB bid request
Other	{{DEMAND_TAG_ID}}		n/a	demand tag id	65432
Other	{{DEMAND_TAG_NAME}}		n/a	Demand Tag Name	Demand tag A URL
Other	{{DEMAND_PARTNER_NAME}}		n/a	Demand Partner	Demand Partner A, Bidder A
Other	{{CREATIVE_NAME}}		n/a	Creative Name	ASPCA Puppy
Other	{{CAMPAIGN_NAME}}		n/a	Campaign name	Share of voice Campaign A
Other	{{ZIP_CODE}}		n/a	Postal code	14526
Other	{{METRO_CODE}}		n/a	Metro COde	37
Other	{{STATE}}		n/a	State	NY
Other	{{ZONE_ID}}	zid=	n/a	zone id	12345
Other	{{EXTRA_EIDS}}	extra_eids=	user.ext.eids	Custom EIDS	Needs source, uid fields id and atype as below "source": "nineforbrands.com.au", "uids": [ { "id": "71bsbsb177171", "atype": "1" } ]	Use "!" as delimiter for extra entries &extra_eids=1S-nineforbrands.com.au,1ID-71bsbsb177171,1ATYPE-1!2S-tenforteas.com.au,2ID-99bsbsb99999,2ATYPE-2
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_CATEGORIES}}	content_categories=	content.cat
Content	{{CONTENT_KEYWORDS}}	content_keywords=	content.keywords
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 Springserve	Mapping 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
OMSDK	{{OMID_PN}}	omidpn=	source.ext.omidpn	Identifier of the OM SDK Integration. The is the same as the "name" parameter of the OMID Partner object.	"source" { "ext": { "omidpn": "publishername_from the macro", "omidpv": "VersionID-from the macro" } }, "imp" [{ "banner": { "api": [7] } }] OR "source" { "ext": { "omidpn": "publishername_from the macro", "omidpv": "VersionID-from the macro" } }, "imp" [{ "video": { "api": [7] } }]	“OMSDK” flag must be enabled on the supply tag and on export tag you must click the macro name in the OMSDK section. The presence of both omidpn= and omidpv= in the tag will also inject the video.api or banner.api field of the outbound bid requests.
OMSDK	{{OMID_PV}}	omidpv=	source.ext.omidpv	(optional) Version of the OM SDK. This is the same as the "versionString" parameter of the OMID Partner object.	"source" { "ext": { "omidpn": "publishername_from the macro", "omidpv": "VersionID-from the macro" } }, "imp" [{ "banner": { "api": [7] } }] OR "source" { "ext": { "omidpn": "publishername_from the macro", "omidpv": "VersionID-from the macro" } }, "imp" [{ "video": { "api": [7] } }]	“OMSDK” flag must be enabled on the supply tag and on export tag you must click the macro name in the OMSDK section. The presence of both omidpn= and omidpv= in the tag will also inject the video.api or banner.api field of the outbound bid requests.

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:

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

Steps on implementing:

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.

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.