Video ads

Serve video ads through Unity Exchange to ensure quality and performance.

Read time 6 minutes

Last updated 2 days ago

Video Ad Serving Template (VAST) is a universal XML schema for serving ads to digital video players. Unity supports VAST 4.0 (standards developed and maintained by the Internet Advertising Bureau (IAB)), and is backward compatible with 2.0 (with the exception of certain features). The Unity SDK parses VAST XML to retrieve video media files and tracking URLs. Ensure that you follow these requirements:

VAST
```
<InLine>
```
must contain all of the required elements to render the video ad. For more information, refer to section 3.4 of the VAST guidelines.
The supported
```
<MediaFile>
```
type is
```
video/mp4
```
. They should include
```
bitrate
```
,
```
delivery
```
,
```
width
```
, and
```
height
```
attributes. For more information, refer to section 3.9 of the VAST guidelines.
Video duration must be between 5 and 30 seconds.
You can wrap VAST tags up to five times.
Companions must be shown full-screen after the initial video ad is finished or skipped.
All HTML markup must reference externally-hosted assets with an absolute URL path that contains
```
https://
```
and a domain. Pointing to assets from
```
file://
```
or a relative URL path does not work.

Include multiple video sizes for varying environments:

Max video file size is 20 MB.
On WIFI connections, the video player will choose a file between 5 and 10 MB.
On cellular connections, the video player will choose a file between 0.5 and 3 MB.
Include video sizes for portrait and landscape modes whenever possible.

Skippable video ads

Publishers control whether the user can skip video ads in their app. Most skippable ads require the user to watch for a fixed number of seconds (determined by the publisher) before allowing them to skip to the end card. Because most skippable inventory allows the user to skip to the end card, Unity highly recommends including one with your video demand. Reach out to your partner manager to learn more about skippable and non-skippable inventory.

Video controls

Unity's video controls overlay will fade into view while the video is playing. Users can hide or show it again by tapping the screen. The overlay includes a progress bar at the bottom of the screen, a privacy icon, and the call to action (CTA). It might include a close button in the top-right corner or a skip icon in the top-left corner.

Video Click Support

A VAST tag must contain a single video click-through in the

<ClickThrough>

node and can contain multiple click-tracking URLs in respective

<ClickTracking>

nodes. For more information, refer to section 3.10 of the VAST guidelines. Ensure that you follow these requirements:

A click-through URL should use
```
https://
```
,
```
market://
```
,
```
 itunes://
```
, or
```
itms://
```
prefixes on respective platforms.
Unity strongly recommends server-side redirects instead of lengthy appended URLs.
Unity does not support click-to-call ads that use the
```
tel://
```
prefix.
Click wrappers can contain additional click tracking.

Video CTAs

During video playback, a call to action (CTA) button appears on the bottom-right of the screen. A user must tap the button to trigger click-through events and open the

<ClickThrough>

URL. The CTA button says "Learn More" by default. If a bundle ID is present in the creative's bid response, the CTA button will say "Install Now".

An Install Now call-to-action button on a video ad.

A Learn More call-to-action button on a video ad.

CTA icons

VAST 3.0 and higher supports the use of icons. The Unity video player displays a square icon alongside the "Install Now" button during video playback for bid responses that include a bundle ID. You can nest a custom icon in the VAST tag. For more information, refer to section 3.11 of the VAST guidelines. Icons should represent the advertised app. Unity does not support displaying any other icons over the video. Ensure that you follow these icon requirements:

Icons should be a
```
<StaticResource>
```
image, with
```
.png
```
,
```
.jpg
```
, or
```
.jpeg
```
extensions.
Icons will be displayed as squares, at 25 x 25 pixels.
Unity does not support icon duration and
```
<IconClickThrough>
```
functionality.


<Icons>	<Icon width="25" height="25">	<StaticResource creativeType="image/png">		<![CDATA[ https://Unity.com/DSP/square_icon_name ]]>	</StaticResource>	</Icon></Icons>

All companions should include a

height

and

width

attribute within the following size limits:

The minimum square width/height is 200 pixels.
The minimum landscape width/height is 480 x 320 pixels.
The minimum portrait width/height is 320 x 480 pixels.

Companion ads

VAST companions appear as a full-screen end card after the video has finished playing. The recommended best practice is to use companions to maximize click-through. Most publishers allow skipping to end cards, so even skippable inventory will show an end card before the user can exit the ad experience.

Companion click support

While an end card is displayed, the user can tap anywhere on the screen to trigger

<CompanionClickTracking>

and

<CompanionClickThrough>

events. There is no Unity CTA placed on top of end cards. For more information, refer to section 3.13 of the VAST guidelines.

End card resource types

Type	Description	Notes
`<HTMLResource>`	HTML markup.	The markup should not contain custom close buttons. This supports MRAID. The creative markup should contain the click-through function within HTML or Javascript instead of a `<CompanionClickThrough>` element. Android devices prioritize HTML end cards over other resource types.
`<StaticResource>`	An asset to be displayed in an `<img>` tag, such as `image/jpeg` , `image/jpg` , `image/gif` , or `image/png` .	Provide the click URL in a `<CompanionClickThrough>` element.

Supported VAST 4.x macros

The following list details the VAST 4.x macros that Unity supports if they are provided in the tracking URL:

```
[ERRORCODE]
```
- Refer to Error codes.
```
[OMIDPARTNER]
```
- An identifier of the OM SDK integration.
- This is the same as the
```
name
```
  and
```
versionString
```
  parameters of the
```
OMIDPartner
```
  object.
```
[REASON]
```
- The reason code for not executing verification.
```
[TIMESTAMP]
```
- (time stamp)
```
[IFA]
```
- A resettable advertising ID from a device-specific advertising ID scheme, such as Apple's ID for Advertisers or Android's Advertising ID, in UUID format or based on the IAB documentation on Guidelines For Identifier For Advertising On OTT Platforms.
```
[IFATYPE]
```
- A string value that indicates the type of IFA included in the
```
[IFA]
```
  macro.
```
[APIFRAMEWORKS]
```
- A list of frameworks supported by the player.
- Values are defined in the AdCOM 1.0 API Frameworks list.
```
[APPBUNDLE(required)]
```
- For app ads, a platform-specific application identifier, bundle, or package name. This identifier cannot be an app store ID, such as the Apple App Store ID.
  - Where required and applicable, but unknown or unavailable, set to -1 or -2, as described in section 6.1 of the IAB documentation on VAST 4.x Macros.
  - When required and not applicable (such as in an app), set to 0.

For more information, refer to the IAB documentation on VAST 4.x Macros.

Troubleshooting

Low impressions

If you experience a high win rate but receive few impressions for a particular video campaign or creative, consider the following:

Cause	Suggested action
The wrapped VAST tag points to a `VASTAdTagURI` that does not return any XML.	Check that the campaign is live. A media file might show up to two hours after it is received.
Video file size too large	Provide at least one media file that is less than 20 MB.
A platform or mobile browser is unable to play the media file.	Verify that media file and tracking URLs are secure. Include a file extension at the end of the URL such as `.mp4` . Although file extensions are not required in URLs, this can reduce MIME type errors for some mobile browsers.

Click-through URLs

If a video click-through URL has a forward slash (

) or plus symbol (

) in the query string, the symbol(s) will be URL encoded with their UTF-8 equivalent. This might interfere with some click redirects and lead to low impressions.

Note

The query string is the portion of the URL after the first question mark (

Character	UTF-8 code
`/`	`%2F`
`+`	`%2B`

For example:

https://domain.com/anything_here_is_fine?this_is_a/query+string

is encoded as:

https://domain.com/anything_here_is_fine?this_is_a%2Fquery%2Bstring

If your click-through URL has special characters, ensure that they still work (either resolve or redirect) when Unity encodes them.

Error codes

Unity sends VAST errors to the VAST tag's

<Error>

tracking URL and replaces the

[ERRORCODE]

macro with one of the following error codes. These errors occur when the ad is about to show, or already showing.

Code	Description
`100`	XML parsing error.
`101`	VAST schema validation error.
`102`	VAST version unsupported.
`200`	VAST format unsupported.
`202`	Video duration is too long or is not formatted as `HH:MM:SS` .
`300`	Wrapper error.
`301`	A `VastAdTagURI` timed out.
`302`	Max wrapper limit (five) exceeded.
`303`	No `<Ad>` found after unwrapping.
`401`	Supported media file not found.
`402`	Media file URI timed out.
`403`	Unsupported media file.
`404`	Media file URI is not supported on iOS.
`499`	No click-through URL.
`600`	General companion ad error.
`601`	Unsupported companion ad size.
`602`	Unable to display companion ad.
`603`	Unable to fetch companion ad resource.
`604`	Valid companion ad resource URL not found.
`699`	Companion ad does not contain a valid click-through URL.
`900`	Undefined error.
`998`	VAST XML content contains an invalid URL.
`999`	Unknown error.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Grow

Unity Ads Android SDK

Unity Ads iOS SDK

LevelPlay SDK

Grow

Video ads

Skippable video ads

Video controls

Video Click Support

Video CTAs

CTA icons

Companion ads

Companion click support

End card resource types

Type

Description

Notes

Supported VAST 4.x macros

Troubleshooting

Low impressions

Cause

Suggested action

Click-through URLs

Character

UTF-8 code

Error codes

Code

Description