DSP Video AD. Delivery API

14 minute read

InJun Kim

REQUEST

SSP DSP

MezzoMedia DSP uses HTTP HOST to create the objects defined below in JSON form to call the DSP interface.
The request object definition follows the OPEN RTB 2.5 specification.

Request object

Field Type Required Description
id string Y request unique ID.
at integer Y 0 : fixed price, 1: first price, 2: second price
tmax integer Y Maximum time (ms).
imp object array Y Refer to the imp object.
app object Y Refer to the app object.
device object Y Refer to the device object.
user object Y Refer to the user object.
bcat string array N Blocked advertiser categories using the IAB content categories.
badv string array N Block list of advertisers by their domains
bapp string array N Block list of applications by their bundle or package names
ext object Y Refer to the ext object.
imp
Field Type Required Description
id string Y impression unique ID
bidfloor float Y The minimum price that can be approved by bidding. ex)4.12
bidfloorcur string Y currency ex) KRW
secure integer Y 0 : HTTP, 1 : HTTPS
video object Y Refer to the video object.
instl integer Y Indicates whether this is a interstitial ad. (default : 0)
* 1 = the ad is interstitial or full screen
* 0 = not interstitial.
displaymanager string Y Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).
displaymanagerver string Y Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile).
video

imp / video

Field Type Required Description
mimes string array Y MIME type. ex) “video/mp4”
w integer Y video width size.
h integer Y video height size.
minduration integer Y minimum seconds video should be played (second).
maxduration integer Y maximum seconds video can be played (second).
protocols integer array Y VAST version. pass it to “3”
startdelay integer Y Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.
* 0 = Pre-Roll
* -1 = Generic Mid-Roll
* -2 = Generic Post-Roll
linearity integer Y 1: Linear / In-Stream 2: Non-Linear / Overlay
delivery integer array Y Pass it to 2 (Progressive).
placement integer Y Video Placement Types
* 1 = In-Stream
* 2 = In-Banner
* 3 = In-Article
* 4 = In-Feed
* 5 = Interstitial/Slider/Floating
ext object N Placeholder for exchange-specific extensions to OpenRTB.(ex, rewarded)
video / ext

imp / video / ext

Field Type Required Description
rewarded integer N Indicates whether this is a rewarded ad.
* 0 = no(non-reward)
* 1 = yes(reward)
app
Field Type Required Description
id string Y publisher ID.
name string N application name.
bundle string Y bundle name, package name.
storeurl string N appstore URL.
cat string array N category.
publisher object Y Refer to the publisher object.
publisher

app / publisher

Field Type Required Description
id string Y publisher ID.
name string N publisher name.
cat string array N category.
device
Field Type Required Description
ua string Y device user agent information.
dnt integer N location tracking enabled, [0 : enable 1 : disable]
ip string Y IPV4 address.
model string N model name.
os string Y OS. ex) iOS, Anroid
osv string Y OS version. ex) 8.1, 9.2
js integer N It is defined as 1 in RTB protocol.
ifa string Y Apple IFA or Google ADID.
user

This is an extension field of MezzoMedia not found in the RTB protocol.

Field Type Required Description
id string Y user unique ID.

Request example (APP)


{
   "id": "cdc-7c6d-4029-dcd|1337",
   "at": 0,
   "tmax": 250,
   "imp": [
      {
         "id": "150226007700",
         "bidfloorcur": "KRW",
         "bidfloor": 0,
         "secure": 0,
         "video": {
            "mimes": [
               "video\\/mp4"
            ],
            "w": 1080,
            "h": 1920,
            "minduration": 5,
            "maxduration": 30,
            "protocols": [
               3
            ],
            "startdelay": 0,
            "linearity": 1,
            "delivery": [
               2
            ],
            "ext": {
               "rewarded": 1
            }
         },
         "instl": 0
      }
   ],
   "app": {
      "id": "test-pub-app-id",
      "name": "test-pub-app-name",
      "bundle": "com.mezzo.co.kr ",
      "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
      "cat": [
         "IAB1"
      ],
      "publisher": {
         "id": "test-pub-app-id",
         "name": "test-pub-app-name",
         "cat": [
            "IAB1"
         ]
      }
   },
   "device": {
      "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
      "dnt": 0,
      "ip": "192.168.1.1",
      "model": "iPhone 7,2",
      "os": "iOS",
      "osv": "8.0",
      "js": 1,
      "ifa": "test-ifa-gaid"
   },
   "user": {
      "id": "923123"
   },
   "ext": {
   }
}

Request example (WEB)


{
   "id": "cdc-7c6d-4029-dcd|1337",
   "at": 0,
   "tmax": 250,
   "imp": [
      {
         "id": "150226007700",
         "bidfloorcur": "KRW",
         "bidfloor": 0,
         "secure": 0,
         "video": {
            "mimes": [
               "video\\/mp4"
            ],
            "w": 1080,
            "h": 1920,
            "minduration": 5,
            "maxduration": 30,
            "protocols": [
               3
            ],
            "startdelay": 0,
            "linearity": 1,
            "delivery": [
               2
            ],
            "ext": {
               "rewarded": 1
            }
         },
         "instl": 0
      }
   ],
   "site": {
      "id": "test-pub-app-id",
      "domain": "test-pub-web-domain",
      "ref": " test-pub-web-ref",
      "cat": [
         "IAB1"
      ],
      "publisher": {
         "id": "test-pub-app-id",
         "name": "test-pub-app-name",
         "cat": [
            "IAB1"
         ]
      }
  },
  "device": {
      "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
      "ip": "192.168.1.1"
  },
  "user": {
      "id": "923123"
  },
  "ext": {
      "price_type": 1,
      "tracking_type": 0
  }
}

RESPONSE

DSP SSP

DSP responds by including the objects defined below in HTTP body.
Object definitions follow the OPEN RTB 2.3 specification.

Bid Response

Response object in JSON format.

Field Type Required Description
id string Y bid request ID.
bidid string Y bid object ID.
cur string Y currency for bidding ex) KRW
seatbid object array Y bid object array.
bid
Field Type Required Description
id string Y bid information managing ID
price float Y bidding price
adm string (XML) Y Refer to the adm object.
nurl string Y impression URL
adomain string array Y advertiser domain
cid string Y advertiser campaign name / id
crid string Y advertiser creative name / id
cat string array Y category
ext object Y Refer to the ext object.
ext
Field Type Required Description
clickurl string Y click tracking URL
viewable string Y tracking URL for more than 20% of the advertising area exposure and play for more than 2 seconds
breakaway string Y tracking url for events that did not finish playing ad

If breakaway URL contains {m_sec}, replace {m_sec} with ad play time to call URL.
For example, if you specified a breakaway value http://breakaway.tracking.com/tracking.do?time={m_sec} and it was broken away after 20 seconds from ad, call http://breakaway.tracking.com/tracking.do?time=20

adm

Object defined by XML.
Object definitions follow the VAST 3.0 specification.

elmt. / prop. Type Required Description
VAST element Y Refer to the VAST definition.
VAST

adm / VAST

elmt. / prop. Type Required Description
version integer (prop.) Y VAST PROTOCOL version. If 3.0, write it with 3.
Ad element array Y Refer to the Ad definition.

adm / Ad

elmt. / prop. Type Required Description
id integer (prop.) N ad ID.
sequence integer (prop.) N ad sequence number.
Inline element Y Refer to the Inline definition.
Inline

adm / Ad / Inline

elmt. / prop. Type Required Description
AdSystem integer N Refer to the AdSystem definition.
AdTitle integer N ad name.
Extensions element N Refer to the Extensions definition.
Error element N tracking URL to call in case of player error.
Impression element Y tracking URL to call at video start.
Creatives element array Y Creative element array.
AdSystem

adm / Ad / Inline / AdSystem

elmt. / prop. Type Required Description
version integer (prop.) N ad engine version.

Element value is the ad engine name.

Extensions

adm / Ad / Inline / Extensions

elmt. / prop. Type Required Description
requestID string N ad request unique ID.
Creative

adm / Ad / Inline / Creatives / Creative

elmt. / prop. Type Required Description
id integer (prop.) N ad number.
sequence integer (prop.) N ad sequence.
Linear element Y Refer to the Linear definition.
Linear

adm / Ad / Inline / Creatives / Creative / Linear

elmt. / prop. Type Required Description
Duration string N video duration / play time. Specifies in hh:mm:ss form.
TrackingEvents element array N Tracking element array.
VideoClicks element N Refer to the VideoClicks definition.
MediaFiles element array Y MediaFile element array
Tracking

adm / Ad / Inline / Creatives / Creative / Linear / TrackingEvents / Tracking

The element value is the HTTP(s) URL for tracking event.

elmt. / prop. Type Required Description
event string (prop.) Y Specifies the event name. ex) start, firstQuartile, midpoint.
offset element array N Specifies the play time that becomes the event condition “hh:mm:ss” form.

The element value is the HTTP(s) URL for the tracking event.

Event Description
start Tracking URL to call when video is started.
firstQuartile Tracking URL to call when video is played 25%.
midpoint Tracking URL to call when video is played 50%.
thirdQuartile Tracking URL to call when video is played 75%.
complete Tracking URL to call when video playing is completed.
progress Tracking URL that is called when a movie is played by the specified offset property.

You can specify different tracking URLs for the same event (which have the same event value and offset value).

VideoClicks

adm / Ad / Inline / Creative / Linear / VideoClicks

The element value is an HTTP(s) URL for handling click events.

elmt. / prop. Type Required Description
ClickThrough string Y destination URL when ad clicks.
ClickTracking string N click event tracking URL.
offset string N Ad can be clicked an ad after playing it for a specified time.

ClickThrough : DSP can handle the click event, and redirect them to the final ad landing.

MediaFile

adm / Ad / Inline / Creatives / Creative / Linear / MediaFiles / MediaFile

elmt. / prop. Type Required Description
delivery string (prop.) N video creative play method. Progressive is supported.
type string (prop.) N video creative type ex) video/mp4
width integer (prop.) N video creative width
height integer (prop.) N video creative height
bitrate integer (prop.) N video creative bitrate

The element value is the path to the video content. (HTTP, HTTPS)

Bid response example


{
   "id": "req-12345-abcde",
   "bidid": "5508",
   "cur": "KRW",
   "seatbid": [
      {
         "bid": [
            {
               "id": "147704390800",
               "price": "60",
               "adm": "%3CVAST+version%3D%223.0%22%3E%0D%0A%3CAd+id%3D%2250096%22+sequence%3D%221%22%3E%0D%0A%3CInLine%3E%0D%0A%3CAdSystem+version%3D%222%22%3EMAN%3C%2FAdSystem%3E%0D%0A%3CAdTitle%3E%0D%0A%3C%21%5BCDATA%5B+20160217_%ED%99%88%ED%94%8C%EB%9F%AC%EC%8A%A4_%ED%99%88%ED%94%8C%EB%9F%AC%EC%8A%A4_%EB%8F%99%EC%98%81%EC%83%81_%ED%85%8C%EC%8A%A4%ED%8A%B8+%5D%5D%3E%0D%0A%3C%2FAdTitle%3E%0D%0A%3CExtensions%3E%0D%0A%3CrequestID%3E%0D%0A%3C%21%5BCDATA%5B+-+%5D%5D%3E%0D%0A%3C%2FrequestID%3E%0D%0A%3C%2FExtensions%3E%0D%0A%3CError%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fd_err%3D%5BERRORCODE%5D%5D%0D%0A%5D%5D%3E%0D%0A%3C%2FError%3E%0D%0A%3CImpression+id%3D%22man_server%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dimps_tracking%0D%0A%5D%5D%3E%0D%0A%3C%2FImpression%3E%0D%0A%3CCreatives%3E%0D%0A%3CCreative+id%3D%2225549%22+sequence%3D%221%22%3E%0D%0A%3CLinear%3E%0D%0A%3CDuration%3E00%3A00%3A30%3C%2FDuration%3E%0D%0A%3CTrackingEvents%3E%0D%0A%3CTracking+event%3D%22start%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_q1%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22firstQuartile%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_q2%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22midpoint%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_q3%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22thirdQuartile%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_q4%26e_version%3D2%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22complete%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_q5%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22progress%22+offset%3D%2200%3A00%3A05%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dimps_video_tracking%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3CTracking+event%3D%22progress%22+offset%3D%2200%3A00%3A15%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dtrack_vast_view%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FTracking%3E%0D%0A%3C%2FTrackingEvents%3E%0D%0A%3CVideoClicks%3E%0D%0A%3CClickThrough%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fad_tracking.mezzo%2F%3Fe_request_type%3Dclick%26e_version%3D2%0D%0A%5D%5D%3E%0D%0A%3C%2FClickThrough%3E%0D%0A%3CClickTracking%3E%3C%2FClickTracking%3E%0D%0A%3COffset%3E00%3A00%3A05%3C%2FOffset%3E%0D%0A%3C%2FVideoClicks%3E%0D%0A%3CMediaFiles%3E%0D%0A%3CMediaFile+delivery%3D%22progressive%22+type%3D%22video%2Fmp4%22+width%3D%22480%22+height%3D%22270%22+bitrate%3D%22350%22%3E%0D%0A%3C%21%5BCDATA%5B%0D%0Ahttp%3A%2F%2Fmtag.mman.kr%2Fvod.mezzo%2F%3Fe_version%3D2%26e_request_type%3Dvod%26i_video_name%3D20161014150027%26d_r%3D1%26i_rs_t%3D3%26d_p1%3D1%0D%0A%5D%5D%3E%0D%0A%3C%2FMediaFile%3E%0D%0A%3C%2FMediaFiles%3E%0D%0A%3C%2FLinear%3E%0D%0A%3C%2FCreative%3E%0D%0A%3C%2FCreatives%3E%0D%0A%3C%2FInLine%3E%0D%0A%3C%2FAd%3E%0D%0A%3C%2FVAST%3E",
               "nurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=imps_tracking",
               "adomain": "http: //adver.co.kr",
               "cid": "2234",
               "crid": "2234",
               "cat": [
                  "IAB1"
               ],
               "ext": {
                  "clickurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=click",
                  "viewable": "http://abc.com/ad_tracking.mezzo/?e_request_type=viewable",
                  "breakaway": "http://abc.com/ad_tracking.mezzo/?e_request_type=breakaway&sec={m_sec}"
               }
            }
         ]
      }
   ]
}

adm example


<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
   <Ad id="50096" sequence="1">
      <InLine>
         <AdSystem version="2">MAN</AdSystem>
         <AdTitle><![CDATA[ 20160217_homeplus_homeplus_movie_test ]]></AdTitle>
         <Extensions>
            <requestID><![CDATA[ - ]]></requestID>
         </Extensions>
         <Error><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?d_err=[ERRORCODE]]]]></Error>
         <Impression id="man_server"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=imps_tracking]]></Impression>
         <Creatives>
            <Creative id="25549" sequence="1">
               <Linear>
                  <Duration>00:00:30</Duration>
                  <TrackingEvents>
                     <Tracking event="start"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_q1&e_version=2]]></Tracking>
                     <Tracking event="firstQuartile"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_q2&e_version=2]]></Tracking>
                     <Tracking event="midpoint"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_q3&e_version=2]]></Tracking>
                     <Tracking event="thirdQuartile"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_q4&e_version=2]]></Tracking>
                     <Tracking event="complete"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_q5&e_version=2]]></Tracking>
                     <Tracking event="progress" offset="00:00:05"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=imps_video_tracking&e_version=2]]></Tracking>
                     <Tracking event="progress" offset="00:00:15"><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=track_vast_view&e_version=2]]></Tracking>
                  </TrackingEvents>
                  <VideoClicks>
                     <ClickThrough><![CDATA[http://mtag.mman.kr/ad_tracking.mezzo/?e_request_type=click&e_version=2]]></ClickThrough>
                     <ClickTracking></ClickTracking>
                     <Offset>00:00:05</Offset>
                  </VideoClicks>
                  <MediaFiles>
                     <MediaFile delivery="progressive" type="video/mp4" width="480" height="270" bitrate="350"><![CDATA[http://mtag.mman.kr/vod.mezzo/?e_version=2&e_request_type=vod&i_video_name=20161014150027&d_r=1&i_rs_t=3&d_p1=1]]></MediaFile>
                  </MediaFiles>
               </Linear>
            </Creative>
         </Creatives>
      </InLine>
   </Ad>
</VAST>

SKAdNetwork Support(iOS14+)

This information is intended to support campaigns with SKAdNetwork enabled in iOS14 version or above.

1 DSPs should register as an Ad Network to Apple’s SKAdNetwork API.
(https://developer.apple.com/documentation/storekit/skadnetwork/registering_an_ad_network)
2 Supply your public key to Apple and set your postback urls.
3 Provide your SKAdNetwork ID to MezzoMedia Manager and
MezzoMedia will get your SKAdNetwork ID(s) added to publishers’ info.plist.
4 If the DSP is responding with a SKAdNetwork enabled campaign, it should respond with SKAdNetwork ID and all relevant fields in the bid response.
5 Advertiser app should be registering its new users to SkAdNetwork via registerAppForAdNetworkAttribution()
6 DSPs should have an install tracking service to handle install data and signature from the SKAdNetwork postback.

Bid Request (SKAdNetwork)

BidRequest / imp / banner / ext / skadn

This object will be populated if all conditions below are met.

1 The DSP has at least one SKAdNetwork ID registered in the publisher’s info.plist.
2 The user’s device is operating on iOS14 or above.
3 The DSP is on MezzoMedia spec.
Attribute Type Required Description Example
version string Y Version of skadnetwork supported. Always “2.0” or higher. “version”:”2.0”
sourceapp string Y ID of publisher app in Apple’s App Store. Should match ‘BidRequest.app.bundle’ “sourceapp”:”000000000”
skadnetids string Y A subset of SKAdNetworkItem entries in the publisher app’s info.plist that are relevant to the DSP. “skadnetids”:[“feyaarzu9v.skadnetwork”]
SKAdNetwork Bid Request Example
{
	"imp":[{
        "ext": {
          "skadn": {
            "version": "2.0",
			"sourceapp": "000000000",
			"skadnetids": ["feyaarzu9v.skadnetwork", "8sRFag4vVC.skadnetwork"]
			}
			}
		}]
}

Bid Response (SKAdNetwork)

BidResponse / imp / banner / ext / skadn

Attribute Type Required Description Example
version string Y Version of SKAdNetwork desired. Must be 2.0 or above. “version”:”2.0”
network string Y Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request. “network”:[“feyaarzu9v.skadnetwork”]
campaign string Y Campaign ID compatible with Apple’s spec. As of 2.0, should be an integer between 1 and 100, expressed as a string. “campaign”:”45”
itunesitem string Y ID of advertiser’s app in Apple’s app store. Should match ‘Bidresponse.bid.bundle’ “itunesitem”:”123456789”
nonce string Y An id unique to each ad response. “nonce”:”123b1a78-b5ef-98ad-1234-ab-c4effa00b8”
sourceapp string Y ID of publisher’s app in Apple’s app store. Should match ‘BidRequest.imp.ext.skad.sourceapp’ 과 매칭 “sourceapp”:”000000000”
timestamp string Y Unix time in millis string used at the time of signature. “timestamp”:”1234567890”
signature string Y SKAdNetwork signature as specified by Apple. “signature”:”ABCDEFGHijkl-lmb…”
SKAdNetwork Bid Response Example
{
	"seatbid": [{
 		"bid": [{
			"ext": {
			"skadn": {
				"version": "2.0",
                "network":"feyaarzu9v.skadnetwork",
                "campaign":"45",
                "itunesitem":"123456789",
                "nonce":"123b1a78-b5ef-98ad-1234-ab-c4effa00b8",
                "sourceapp":"000000000",
                "timestamp":"1234567890",
                "signature":"ABCDEFGHijkl-lmbKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==""
				}
			}
		}]
	}]
}

Updated: