VAST and VMAP Parameters

The following tables list and describe parameters to request and filter ads and to pass in more information for tracking purposes .

Note: A few of these parameters may have values containing characters which must be URL encoded. For example, the m parameter contains the model name of the device, which may contain a space. This space must be URL encoded to %20.

Response Format Parameters

The following parameters relate to the template and format of the response.

Parameter Descriptions Required
rt
Response Template: the format of the response ticket. Possible values:
  • vast_2.0
  • vast_2.0.1
  • vast_3.0 (preferred when requesting VAST tickets)
  • vmap_1.0

Example: rt=vmap_1.0

Yes
tf
Ticket Format indicates the format of the response. Possible values are:
  • xml (default)
  • json
No

Ad Type and Insertion Policy Parameters

The following parameters relate to what types of ads are returned and where and when ads should play. Many of these parameters override the ad insertion policies set in Pulse. For more information about ad insertion policies, refer to Ad Insertion Policies.

Parameter Descriptions Required
tt
Ticket Type indicates the type of ads to request. Supplied as a comma separated string composed of 1 or more of the following values:
  • p: pre-roll
  • m: mid-roll, must be used in combination with bp parameter
  • po: post-roll
  • o: overlay, must be used in combination with obp or cdparameter
  • pa: pause ad
Note: If no ticket types are specified, then all of the above are requested. However, you must keep in mind that you still have to provide additional parameters as indicated to successfully request mid-rolls and overlays.

Example: tt=p,m,po, to request pre-, mid-, and post-rolls

No
bp

Break Positions for mid-roll ads. Comma separated string of numbers that indicate times when cuepoints are triggered.

Example: tt=m&bp=10,20, which means that mid-rolls are shown after 10 seconds and 20 seconds of video content playback.

Only in case mid-rolls were requested.
obp

Overlay Break Positions sets the precise times at which overlays should be shown. This means that overlays are only shown when you specify the exact times at which they should be shown. The insertion policy in Pulse only dictates how long overlays are shown for.

Comma separated string of numbers that indicate times when cuepoints are triggered.

Example: tt=o&obp=10,20, which means that overlays are shown after 10 seconds and 20 seconds of video content playback.

Only in case overlays were requested for position-based overlays.
op

Overlay Position overrides when the first overlay is shown according to the insertion policy. When specifying this parameter, it must be done in combination with the content duration (cd) parameter,

Note: This parameter only has effect if no overlay break positions are specified in the request through the obp parameter.

Valid values are between 0 and 60. Any other value is automatically transformed to 60 seconds. The default value is 20 seconds.

Example: tt=o&op=55&cd=1050.750

No
cf
Content Form indicates if the video content is short or long. Depending on this value, different ad insertion policies may apply to the ad request. Possible values are:
  • short_form (default)
  • long_form

Example: cf=long_form

No
f
Flags override ad insertion policies by turning off requests for certain ad types. Supplied as a comma separated string composed of 1 or more of the following values:
  • nocom: the ad request returns no ads nor track inventory. You could use this for content where displaying ads is inappropriate.
  • noprerolls: the response contains no pre-rolls.
  • nomidrolls: the response contains no mid-rolls.
  • nopostrolls: the response contains no post-rolls.
  • nooverlays: the response contains no overlays.

Example: f=noprerolls,nomidrolls

No
cd

Content Duration indicates how long the video content is. In case of time-based overlays, this value influences how many overlays are returned in the response, based on the time after which the first overlay is shown and the timespan between subsequent overlays as defined in the insertion policy. However, the content duration has no effect on overlays in case overlay break positions are specified in the request through the obp parameter.

The content duration should be provided in seconds and milliseconds, separated from each other with a dot (.).

Example: cd=300.250

No
xpb
eXplicit PassBack parameter is used to enable passbacks for 3rd party ads. In case the 3rd party ad is not available for whatever reason, one or more backup ads are made available, with the last ad in the passback chain always being a Pulse ad. This way Pulse can ensure that an ad is shown. Possible values for this parameter are:
  • 0: passbacks disabled (default)
  • 1: passbacks enabled
Note: the video player needs to be able to handle VPAID 1.0 (Flash) ads for this functionality to work.

Example: xpb=1

No
tbbl

Time Based Breaks Length indicates the maximum duration in seconds for linear ad breaks, when the time based breaks feature is enabled for your account. This setting may override the amount of ads returned as set in the insertion policies for pre-, mid- and post-roll ad breaks, in case the total length of the ads would otherwise exceed the set ad break length.

Refer to Ad Insertion Policies for more information regarding time based breaks, where to set it and its limitations.

Note: Adding the maximum linear break duration in an ad session request to Pulse sets the maximum duration for each linear break requested, even if no maximum duration was previously defined in the applicable ad insertion policy in Pulse.

Example: tbbl=60 indicates that each linear ad breaks may only be 60 seconds long.

No
pp

Pre-roll Positions is used to override the number of ads in a pre-roll ad break set in the insertion policies.

Example: pp=3

No
mp

Mid-roll Positions is used to override the number of ads in a mid-roll ad break set in the insertion policies.

Example: mp=2

No
pop

POst-roll Positions is used to override the number of ads in a post-roll ad break set in the insertion policies.

Example: pop=2

No

Campaign, Goal and Ad Filtering Parameters

The following parameters are used to select ads from specific goals and campaigns based on which targets are defined for them in Pulse. For more information about targeting rules, refer to Targeting Rules.

Parameter Descriptions Required
s

Shares indicate a case-insensitive comma separated list of categories and partners targeted by the ad request.

Note: You can only provide one category and one partner, either with their unique identifier or one of their aliases.

Example: s=e0cfa44c-f402-4535-a45e-1be63bc4259a,5a30a168-7398-456e-92eb-29d03c0d0f97 or s=my-category,my-partner

No
t

Tags indicate a case-insensitive comma separated list of tags targeted by the ad request. In case of multiple tags, then campaigns and goals matching one and/or more tags are eligible for selection.

For example, if you specify two tags, "youth" and "games", then your pool of eligible campaigns and goals may target:
  • only "youth",
  • only "games",
  • "youth" or "games", or
  • "youth" and "games".

Example: t=youth,games

No
dcid

Device Container ID overrides the automatic device container detection in Pulse, in order to request ads for a specific device container. You must provide a valid ID or short name (case-sensitive) of one of the device containers configured for your account, otherwise the request fails to return any ads.

Warning: Providing this parameter directly affects the device on which inventory, impressions, quartiles, and so on, are tracked in Pulse. dcid should only be used for testing purposes.

Example: dcid=96307a7d-e62e-4705-9aff-9c4b0f449945 or dcid=ios_phones

No

Asset Filtering and Sorting Parameters

The following parameters filter out assets (media) files based on the values passed in.

Parameter Descriptions Required
afr
Asset FilteRing is used to enable or disable filtering of the best asset type for your specific integration, based on device detection. It is turned on by default, and the possible values are:
  • 0: filter off
  • 1: filter on (default)

Example: afr=0

No
vbw

Video BandWidth indicates the maximum bandwidth in kbps of requested video ads. If no maximum bandwith is set, then defaults apply depending on the device and platform, see Defaults for Bandwidth, Width, and Height.

Example: vbw=1500

No
vwt

Video WidTh indicates the preferred width of video ads in pixels. When providing this parameter, then the assets with approximately the preferred width are sorted higher in the response than any other assets. If no width is set, then defaults apply depending on the device and platform, see Defaults for Bandwidth, Width, and Height.

Example: vwt=800

No
vht

Video HeighT indicates the preferred height of video ads in pixels. When providing this parameter, then the assets with approximately the preferred height are sorted higher in the response than any other assets. If no height is set, then defaults apply depending on the device and platform, see Defaults for Bandwidth, Width, and Height.

Example: vht=600

No
Table 1. Defaults for Bandwidth, Width, and Height
Device (group) and/or platform Bandwidth Width Height
All computers (laptops, desktops, ...) using a web browser 800 768 432
Apple computers (laptops, desktops, ...) using an installed application using the CFNetwork Framework 400 960 640
YouView IPTV 720 1024 576
AppleTV 1904 1280 720
All tablets, unless specified otherwise 500 1024 768
All mobile phones, unless specified otherwise 400 480 320
iPhone 4 or higher, and all Apple tablets and phones using iOS 4.3 or higher 400 960 640
Windows phone 800 768 432

Tracking and Reporting Parameters

The following parameters may be passed in with the request, but do not affect the returned ads. These parameters are for reporting and tracking purposes only, and many of them are used to replace placeholder macros in trackers defined Pulse. For more information on macros, see Appendix D - Pulse Macros.

Parameter Descriptions Required
rnd

RaNDom is a random string used for cache busting, so the viewer's browser does not use cached tracking URLs. For more information about cache busting, see the Cache Busters article on our Community site.

Example: rnd={random}

No
m

Model enables you to specify the model of the device for your own tracking purposes. When you specify the device model, then the {request.model} placeholder you may have specified in a tracker is replaced by this value. Examples of device models are Nexus 7, iPhone 6, iPad Air 2, and so on.

Example: m=iPad%20Pro

No
pf
PlatForm is used to pass in platform information for your own tracking purposes. Possible values are:
  • fl_[version]: for a Flash based ad player.
  • and_[version]: for a native Android ad player.
  • ios_[version]: for a native iOS ad player.
, where [version] is the version of the platform.

Example: pf=and_6.0.1

No
st
Supported Tracking enables you to override the default tracking events included in the response and the behaviour of tracking for some events. This parameter is supplied as a comma separated list of event numbers, and built up as follows:
  • To include an event, add its number to the list.
  • To exclude an event, add its number preceded by a minus (-) sign to the list.
  • To modify an event, add its number followed by a colon (:) and then the modifier number to the list.
There are two tracking events that have modifiers:
  • Impression tracking event (0). In case there is no suitable ad for a particular position in an ad break, inventory should be tracked. The following behaviours of inventory tracking are available:
    • 0: an empty ad is sent, containing only an impression tracking event, which should be triggered to track inventory. This is the default behaviour for all plugin, ad player and SDK integrations with Pulse.
    • 1: all empty inventory is automatically tracked on the backend when a ticket is requested. This is the default behaviour for VAST integrations.
    • 2: a VAST ticket is sent, containing only an error tracking event, which should be triggered to track inventory. This is the default behaviour for VMAP integrations.
  • Click-through tracking event (20):
    • 0: track click-through events through an HTTP redirect, which is the default behaviour.
    • 1: track click-through events through the ClickTracking node of the ticket.

Example: st=0:1,-7,10 to transform the impression tracker to track inventory immediately in Pulse when the ticket is requested, to exclude the close tracking event and to include the interaction tracking event.

No
trs
TRacking Scheme overrides the protocol (HTTP or HTTPS) for the tracking links returned in a response. Possible values are:
  • http
  • https
Note: The default value for trs depends on the setting for your account. Ask your Account Manager to know what this is.
Note: The value of the trs parameter only influences the tracking URLs to track events to Pulse. Any external tracking URLs set in Pulse are not affected, nor are any tracking URLs in third party VAST tickets.

Example: trs=http

No
ci

Content Id allows you to pass in the id of the content (video, page, ...) as a string, which can then be forwarded to 3rd party URLs through the macro functionality in tracking URLs. This enables you to track and report on which content certain ads were displayed.

Example: ci=this_is_my_video or ci=1238-dd89-fe12-4aab

No
tid

Ticket ID is a random UUID that connects different ad requests from the same session. A new UUID is generated by Pulse the first time you make an ad request in the session, and is inserted into each tracking URL of the first response. You should then pass in this UUID in each subsequent request for the same session.

This ensures clash protection in the session.

No
pid

Persistent ID is a UUID that identifies the end user and persists across sessions. This parameter should be generated the very first time a viewer uses the player. The parameter should be stored and reused for every future session.

Set it through a cookie or pass it as a request parameter. It is used for frequency capping.

No

Parameters Used for Testing Purposes

The following parameters are used to test your campaigns, goals and ads.

Parameter Descriptions Required
vppreview

VideoPlaza PREVIEW is used to request a specific ad for previewing purposes without returning or recording any tracking events.

Example: vppreview=58f1a009-0bd1-47f9-ad3c-8946b1cf8863

No
xaid

eXplicit Ad ID is used to request a specific ad and should only be used to verify that the requested ad works in your integration.

Example: xaid=58f1a009-0bd1-47f9-ad3c-8946b1cf8863

No
xgid

eXplicit Goal ID is used to request ads from a specific goal and should only be used to verify that requesting ads from this goal works in your integration.

Example: xgid=57c30c01-6e4f-431f-a762-fe2d5e85e672

No
xcid

eXplicit Campaign ID is used to request ads from a specific campaign and should only be used to verify that requesting ads from this campaign works in your integration.

Example: xcid=81029df4-b238-441d-b79e-9ecbfdb627af

No

Was this article helpful?