Video ads

Video ads rely on the VAST (Video Ad Serving Template) standard. VAST is an XML document that acts as a set of instructions for the publisher's video player, specifying where to download the video file, which tracking pixels to fire at the 25%, 50%, and 100% completion marks, and where to direct the user upon a click.

Object imp.video

The SSP includes video player parameters in the request so the DSP responds with a video creative that the player can actually show.

Parameter

Description

mimes

Supported formats, which typically include ["video/mp4"] for in-app and web environments, and application/javascript if the player supports interactive scripts (legacy VPAID).

minduration

Minimum video duration in seconds, such as 5 seconds.

maxduration

Maximum video duration in seconds, such as 30 seconds.

protocols

VAST versions — an array of numbers indicating which VAST standard versions the player supports. For example:

  • 2 = VAST 2.0
  • 3 = VAST 3.0
  • 7 = VAST 4.0
  • 8 = VAST 4.0 Wrapper

plcmt

Video placement type for the impression. The list of values is described in more detail here.

w

Width of the player window.

h

Height of the player window.

linearity

Possible values:

  • 1: Linear, which means the video takes over the entire player and pauses the main content.
  • 2: Non-linear, which means the video ad overlays the main content (like an overlay banner at the bottom of the screen).

VAST protocol

The video player parses the XML and performs the following actions:

  1. <Impression>: Once the video starts playing, the player uses this URL to notify the DSP so it can register an impression.
  2. <MediaFiles>: Contains the link to the MP4 file, which the player downloads and plays.
  3. <TrackingEvents>: Tracks video completion progress (quartiles). The player must send a ping to the DSP server when the user reaches 25% (firstQuartile), 50% (midpoint), 75%, and 100% (complete) of the video.
  4. <VideoClicks>: If the user clicks the player, they're redirected to the URL specified in <ClickThrough>, while a statistics ping is sent to the URL in <ClickTracking>.

Error tracking pixels

Video ads can encounter issues like missing files, unsupported formats, or wrapper timeouts. To handle this, VAST provides an <Error> tag. When a player can't play an ad, it sends a request to this URL with an error macro (such as [ERRORCODE]=400) to inform the DSP why the ad impression failed.

For more information on VAST error types, see the official IAB VAST 3.0 documentation.

Sample request

{
  "id": "req-video-999",
  "imp": [
    {
      "id": "imp-1",
      "bidfloor": 5.00,
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "minduration": 5,
        "maxduration": 15,
        "protocols": [ 2, 3, 5, 6 ], 
        "w": 1080,
        "h": 1920,
        "placement": 5, 
        "linearity": 1,
        "api": [ 7 ] 
      }
    }
  ],
  "app": {
    "bundle": "com.game.racer"
  }
}

Response example

In its response, the DSP sends the bid and places the VAST XML (either the raw code or a link to it) in the adm field.

Alert

The XML string within adm in actual JSON responses contains escaped quotes (\").

{
  "id": "req-video-999",
  "seatbid": [
    {
      "seat": "dsp-video-1",
      "bid": [
        {
          "id": "bid-777",
          "impid": "imp-1",
          "price": 6.50,
          "nurl": "https://dsp.com/win?bid=777&price=${AUCTION_PRICE}",
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\"><Ad id=\"12345\"><InLine><AdSystem>DSP_Name</AdSystem><AdTitle>Promo Video</AdTitle><Impression><![CDATA[https://dsp.com/track/impression?bid=777]]></Impression><Creatives><Creative><Linear><Duration>00:00:15</Duration><TrackingEvents><Tracking event=\"firstQuartile\"><![CDATA[https://dsp.com/track/q1]]></Tracking><Tracking event=\"midpoint\"><![CDATA[https://dsp.com/track/q2]]></Tracking><Tracking event=\"thirdQuartile\"><![CDATA[https://dsp.com/track/q3]]></Tracking><Tracking event=\"complete\"><![CDATA[https://dsp.com/track/complete]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[https://landing.brand.com]]></ClickThrough><ClickTracking><![CDATA[https://dsp.com/track/click]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"1080\" height=\"1920\"><![CDATA[https://cdn.dsp.com/video/ad_1080x1920.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>"
        }
      ]
    }
  ]
}

Alert

Since video files typically range from 3 to 15 MB, slow load times in mobile games mean the video ad can't be shown right after an auction win. Instead, the SDK downloads the MP4 file in the background (caching it on the device) and plays it once the user reaches the right moment in the game.

Previous
Native ads
Next
Interstitial and rewarded ads