Video ads
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. - Supported
<MediaFile>
types includevideo/mp4
, andvideo/webm
. They should includebitrate
,delivery
,width
, andheight
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 fromfile://
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-10 MB.
- On cellular connections, the video player will choose a file between 0.5-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://
, oritms://
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”.
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.
Example CTA icon code
<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. |
|
<StaticResource> | An asset to be displayed in an <img> tag, such as image/jpeg , image/jpg , image/gif , or image/png . |
|
<IframeResource> | A string to be used as “src” in an iframe. |
|
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
andversionString
parameters of theOMIDPartner
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.
- A string value that indicates the type of IFA included in the
[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 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.
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 .webm or .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. |