Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

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. 

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

...

Description

...

Example values

...

Notes

...

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

...

weather.com

...

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

...

General

...

{{CACHEBUSTER}}

...

cb=

...

random number to prevent caching

...

3708662946268

...

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

...

Player

...

{{MUTE}}

...

mute=

...

is player muted

...

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

...

Media

...

{{CONTENT_ID}}

...

cid=

...

content id

...

Media

...

{{ENCODED_VIDEO_TITLE}}

...

vt=

...

encoded video title

...

Media

...

{{VIDEO_ID}}

...

vid=

...

video id

...

Media

...

{{VIDEO_URL}}

...

v_url

...

encoded video url

...

GDPR

...

{{CONSENT}}

...

consent=

...

A consent string passed from various Consent Management Platforms (CMP's)

...

TBD

...

Mandatory for all European traffic for GDPR

...

GDPR

...

{{GDPR}}

...

gdpr=

...

A flag for European Union traffic consenting to advertising

...

1 (true, consenting) or 0 (false, non-consenting)

...

Mandatory for all European traffic for GDPR

...

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

...

{{DETECTED_URL}}

...

url as detected by SpringServe

...

Detected

...

{{DETECTED_ENCODED_URL}}

...

encoded url as detected by SpringServe

...

Detected

...

{{DETECTED_DOUBLE_ENCODED_URL}}

...

double encoded url as detected by SpringServe

...

Detected

...

{{DETECTED_HEIGHT}}

...

height as detected by SpringServe

...

Detected

...

{{DETECTED_WIDTH}}

...

width as detected by SpringServe

...

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

...

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

...

{{DEVICE_BRAND_NAME}}

...

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

...

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.

  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.