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 include video/mp4, and video/webm. 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-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://, 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”.

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#

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:

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.

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.