creative formats - Unity-Technologies/unity-ads GitHub Wiki

/* Title: Supported creative formats Description: Specs for supported creative formats Sort: 8 */

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, 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>

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 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 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.

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.

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.

• 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.

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.

• 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 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>

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.

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](time stamp) 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