Knowledge base

Supported creative formats

Unified Auction supports mobile static display ad (HTML) and video ad (VAST) formats. This article outlines specifications and best practices for Demand Side Platform (DSP) partners.

Static display ads

Static display, display interstitial, and display ads refer to the same ad format in Unity, as these are commonly used for interstitial Placements with static graphic assets. This format typically uses an image with a hyperlink or click event to a destination URL from the advertiser. For example:

<a href="https://click-destination.com"><img src="https://ad-image.jpg"></a>

Static display ad specs

The following are requirements for display ad formats:

  • Content must be formatted as a snippet of HTML (or JS) code, not as a full HTML document or web page.
  • If the content was created with JavaScript only, it must be wrapped with <script> tags.
  • The Unity SDK renders ad markup within the webview as full-screen on mobile devices. However, the advertising partner is responsible for scaling and centering content. Unity loads content to the top-left corner by default. To avoid this, use CSS to center your content in various mobile screen sizes.

Unity highly recommends taking advantage of information available in the Unified Auction bid request to send assets that are optimized for the device, platform, and network connection represented in the request.

Example display ad

Example of HTML with hyperlink:

<style>html, body { margin: 0; padding: 0; width: 100%; height: 100%; vertical-align: middle; } html { display: table; } body { display: table-cell; vertical-align: middle; text-align: center; -webkit-text-size-adjust: none; } </style><a href="https://click-link-with-tracking.com/click?with-click-information"><img src="https://host-url.com/display/ad_image.fig" width="320" height="480"></a><img height="1" width="1" src="https://impression-tracking.com/pixel?id=1234">

Example of HTML with JS script:

<script src="https://display-ad.com/ad-location-js-file"><script><style>some css style</style><img src="https://impression-pixel-url">

Video ads

Video Ad Serving Template (VAST) is a universal XML schema for serving ads to digital video players. Unity supports VAST 3.0 (standards developed and maintained by the Internet Advertising Bureau (IAB)), and is backwards compatible with 2.0, with the exception of certain features.

  • Unity reporting includes events such as impression, playback quartiles, and VPAID interaction-based events.
  • Unity supports rewarded-video and non-rewarded video.
  • Unity does not support custom close and will provide a overlay with a close button in the top right corner.

Unity SDK parses VAST XML to retrieve video media files to play and send relevant event-based tracking URLs.

How VAST works in Unity

A typical VAST XML template contains:

  • Impression and Error URLs to track each event.
  • Information on the video length, and URLs for hosted assets.
  • Video-tracking URLs for video start, first quartile, midpoint, third quartile, and completion events.
  • Click-tracking URLs and destination URLs for video click events.
  • Optional companion ad information for the video asset, tracking, and click-through URLs.

Important: The Unity SDK parses VAST XML to retrieve video media files and fire relevant tracking URLs. If the XML is not formatted with the correct media assets, the SDK will fail to render the ad despite receiving the VAST bid response. This will negatively impact revenue.

Video ad specs

The following are requirements for video ads:

  • We support select features of VAST up to VAST 4.0, for linear video ads only.
  • VAST InLine contains all the required elements to render the video ad.
  • VAST tags can be wrapped up to 5 times.
    • A VAST should point to another VAST XML in the node.
  • Supported video media files include:
    • MIME type only 'video/mp4' for both iOS and Android.
    • Video duration between 6 and 30 seconds.
  • Unity recommends that you send multiple sizes of video:
    • Max video file size is 20MB. Max bitrate is 500 kbps.
    • On WIFI connections, the video player will choose a file between 5 to 10MB.
    • On Cellular connections, the video player will chose a file between 0.5 to 3MB.
  • Include bitrate, delivery, type, width, height as tag attributes.
  • Unity's privacy icon will appear in the bottom of the screen.
  • Unity supports companion ads that appear after the initial video ad completes:
    • <StaticResource> as an image/jpeg, image/jpg, image/gif, or image/png.
    • <HTMLResource> as a "snippet" of HTML code.
  • For click events, the click-through URL should be a single item, while the click-tracking URL may be multiple items.
    • Landscape dimensions are 480 x 320 pixels.
    • Portrait dimensions are 320 x 480 pixels.

Best practices

  • For a VAST XML schema, please see the example XML format below.
  • Limit VAST wrapper redirection to 2-3. Check the final URL points for the appropriate VAST XML file.
  • Video bitrate cannot exceed 512kpbs.
  • Video duration: Duration tag is required, and should be between 6 and 30 seconds in HH:MM:SS format and this should match the length in your bid response.
  • Ads with companions have a greater chance of click through.
  • All tracking and resource URLS should be secure and use HTTPs.
  • MediaFile urls should end in a filetype extension because some mobile browsers may need this to display the video.
  • Leave a space in each corner for the overlay. Add two pictures.

Open Measurement specs

Unity Ads supports Open Measurement-capable creatives. To format your creatives for OM in VAST:

  • For VAST versions 4.1 and higher, include <AdVerifications> in the VAST tag. For VAST versions 4.0 or lower, include AdVerifications> as an <Extension> under <Extensions>.
  • In the <Verification> tag, include the following:
    • Your vendor key, which is used to identify whether your verification script must receive any additional parameters.
    • Your verification script inside the <JavaScriptResource> tag.
    • <VerificationParameters> are optional.

For example:

<AdVerifications>
    <Verification vendor="company.com-omid">
        <JavaScriptResource apiFramework="omid" browserOptional="true">
            <![CDATA[https://verification.com/omid_verification.js]]>
        </JavaScriptResource>
        <VerificationParameters>
            <!CDATA[verification params key value pairs]]>
        </VerificationParameters>
    </Verification>
</AdVerifications>

For more information, see the IAB documentation on VAST 4.1 Open Measurement support.

OM verification script guidelines

  • Register session observers, video, and ad events as soon as the script runs (this simplifies event management and ensures that all events are called in order).
  • When registering the session observer, always include a vendor key that matches the vendor='key' attribute in your <Verifications> node.
  • See this example of a simple verification script.

Example XML formats

Example VAST Linear ad with Companion in <InLine>:

<VAST version="3.0">
    <Error id="to-track-error"><![CDATA[http://error-tracking-url]]></Error>
    <Ad id="ad_id">
        <InLine>
            <AdSystem>2.0</AdSystem>
            <AdTitle>ad title</AdTitle>
            <Impression id="to-track-impression"><![CDATA[http://impression-url]]></Impression>
            <Error id="to-track-error"><![CDATA[http://error-tracking-url]]></Error>
            <Creatives>
                <Creative>
                    <Linear>
                        <Duration>00:00:15</Duration>
                        <TrackingEvents>    
                        // start, firstQuartile, midepoint, thirdQuartile, complete, mute, unmute
                            <Tracking event='start'><![CDATA[http://tracking-url]]></Tracking>
                            ....
                        </TrackingEvents>
                        <VideoClicks>
                            <ClickThrough><![CDATA[https://video_click.com]]></ClickThrough>
                            <ClickTracking><![CDATA[https://video_click_tracking.com]]></ClickTracking>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile delivery='progressive' width='16' height='9' type='video/mp4' bitrate='600' apiFramework='NONE'><![CDATA[https://media_file_site.your_file.mp4]]>
                            </MediaFile>
                            //  ... multiple media files per quality
                        </MediaFiles>
                    </Linear>
                </Creative>
            <Creative>
                <CompanionAds>  // For end card
                    <Companion>   // Can be HTMLResource or StaticResource.
                        <StaticResource creativeType="image/jpeg">
                            <![CDATA[end card url]]>
                        </StaticResource>
                        <TrackingEvents>
                            <Tracking event='creativeView'><![CDATA[https://endcard_tracking]]></Tracking>
                        </TrackingEvents>
                        <CompanionClickThrough><![CDATA[[https://click_url](https://click_url)]]></CompanionClickThrough>
                        <CompanionClickTracking><![CDATA[https://tracking_url]]></CompanionClickTracking>
                    </Companion>
                </CompanionAds>
            </Creatives>
        </InLine>
    </Ad>
</VAST>

Example VAST in <Wrapper>:

<VAST version="2.0">
    <Ad id="1234">
        <Wrapper>
            <Error><![CDATA[https://vast_wrapper_error.tracking.com]]></Error>
            <Impression>...</Impression>
            <VASTAdTagURI><![CDATA[http://vast-ad--url]]></VASTAdTagURI>  // point to inline xml
        </Wrapper>
    </Ad>
</VAST>

Troubleshooting

Here are some possible reasons that a bid may win an auction, yet not have impressions:

  • Blank XML: Returned xml from Wrapper VASTAdTagURI is blank or malformed.
  • XML parsing error: Missing required tag elements like <VAST>, <Duration>, <MediaFile>.
  • Video file size too large: Available <MediaFile> in video/mp4 is over 20 MB size.
  • No Impressions: Please include a file extension in the url of the mediafile. Although not required, this can reduce MIME type errors for some browsers.
  • Video duration too long: Duration exceeds 40 seconds.

Error Reporting

Overview of error codes

Unity fires an <Error> tracking URL with an associated error code:

* `100`: XML parsing error 
* `20X`: Duration or size unsupported  
* `30X`: Wrapper-related errors 
* `40X`: Media file-related errors 
* `60X`: Companion ad-related errors 
* `90X`: Any other undefined error 
  • Support OMIDPARTNER, TIMESTAMP macros in all tracking pixels
  • Support [REASON] macro for ad verification tracking urls. Reason codes are listed below:
    • 1: VERIFICATION_RESOURCE_REJECTED
    • 2: VERIFICATION_NOT_SUPPORTED
    • 3: ERROR_RESOURCE_LOADING

Unity VAST error codes

Error code Description
100 XML parsing error.
101 Schema validation error.
102 Unsupported version.
200 Unsupported format.
202 The video duration is too long or is not formatted properly (HH:MM:SS).
203 The size is unsupported.
300 General wrapper error.
301 Wrapper URI timeout
302 Max wrapper limit (of 5) reached. Unity tries a maximum of 5 routes to fetch VAST content through VASTAdTagURI.
303 No ads were found in Wrapper
400 Unable to play linear.
401 The supported video media file was not found in the media URL
402 The media file timed out.
403 The received media files are unsupported. Make sure they are 'video/mp4' type with a maximum file size of 20 MB.
404 The media file url is not supported in iOS. Make sure it uses HTTPS protocol.
499 Expected a VAST Ad but provided VPAID
600 Companion Ad (end card) has a general error.
601 Companion Ad (end card) size is unsupported. The minimum image size is 320 x 480 pixels (portrait) or 480 x 320 pixels (landscape) or 200 x 200 pixels (square).
602 The Companion Ad (end card) is unable to display.
603 Unable to fetch the Companion Ad (end card).
604 A valid Companion Ad (end card) resource URL was not found.
699 The Companion Ad (end card) does not contain a valid ClickThrough URL.
900 Undefined error.
998 Vast xml content contains invalid URL.
999 Unknown error.
Still need help? Get in touch!
Last updated on 16th May 2022