OpenRTB DSP Integration Guide

Table of contents

  1. Introduction
  2. Changelog
  3. General Info
    1. Features
  4. Integration process
  5. BidRequest
    1. bidrequest: objects and parameters
    2. source: parameters
    3. device: parameters
    4. user: parameters
      1. user.ext: parameters
    5. ext: parameters
    6. site: parameters
      1. site.ext: parameters
    7. imp: objects and parameters
      1. native: objects and parameters
      2. banner: objects and parameters
    8. request: parameters
    9. assets: parameters
    10. title: parameters
    11. img: parameters
    12. data: parameters
    13. BidRequest example
      1. Native
      2. Banner
      3. Native-push
  6. BidResponse
    1. Object: BidResponse
    2. Object: SeatBid
    3. Object: Bid
    4. Native Markup Response Object (seatbid.bid.adm)
    5. Banner Markup Response Object
    6. BidResponse example
      1. Native
      2. Banner
      3. Native-push
  7. Targeting settings of advertising campaign
  8. Cookie matching
  9. Bidding recommendations
  10. Appendix A ext.ad_types
  11. Appendix B ext.imgsizeid
  12. Appendix C ext.category
  13. Appendix D imp.native.request.plcmttype
  14. Appendix E Content Categories

Introduction

This document describes all the technical aspects of connecting the DSP (Demand-Side Platforms) to the MGID SSP platform.

For detailed information about real time bidding, we recommend to download the final OpenRTB 2.5 specification from the link below:

OpenRTB-API-Specification-Version-2-5-FINAL.pdf

Information about the implementation of Native advertising for RTB can be found here:

https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf

 

Changelog

Version Description Date
1.0 Initial version 19.04.2018
1.01 Added recommendations for the amount of the bet 25.04.2018
1.02 Added description of the field BidResponse.bid.crid 27.04.2018
1.03 Added macroses for imptrackers 31.08.2018
1.04 Added site.cat field 24.09.2018
1.05 Fixed errors in the description of the adm parameter 05.10.2018
1.06 Added new pchain field 08.10.2018
1.07 Changed BidResponse.bid.crid field to required 16.10.2018
1.08 Added BidResponse.banner field parameters, BidResponse.bid.burl field bid request and bid response examples for banner 17.10.2018
1.09 Added native parent object to native bidrequest payload (BidRequest.imp[].native.request) 31.10.2018
1.10 Added BidRequest.user.ext.pageview_number field 15.11.2018
1.11 Added macroses for BannerResponse.seatbid[].bid[].adm 16.11.2018
1.12 Added bidRequest.device.os 26.12.2018
1.13 Added bid request and bid response examples for native-push 11.01.2019
1.14 Fixed adm parameter description at the response example for native push 09.07.2019
1.15 Auction type changed from second price to first 09.07.2019
1.16 Added BidRequest.ext.landing_types field 29.07.2019
1.17 Added BidRequest.user.ext.eids 10.09.2019
1.18 Added traffictype & trafficsource parameters to BidRequest.site.ext 16.09.2019
1.19 Billable event changed to viewable impression - bid.burl 29.01.2020
1.20 Added BidRequest.imp.tagid 19.03.2021

 

General Info

The MGID SSP platform supports protocol OpenRTB 2.5 banner, native 1.1 and native 1.2. On the SSP side pre-targeting is supported by various parameters 

Features

Maintenance of statistics:

  • basic statistics are maintained on the SSP side
  • funds are withdrawn only if there is a impressions shown to an end user
  • the most optimal scenario is when DSP sends both NURL and BURL in the bid response. Here, NURL call occurs on the winning in the auction event, and BURL call occurs on the impression’ was shown to an end-user event
  • In case when BURL is not present in bid response and only NURL is sent, NURL call occurs on the impression’ was shown to a comsumer event (the logic of BURL) and no auction winning event is sent
  • if both BURL and NURL are absent in the DSP’ bid response the discrepancies in the statistics will not be considered
  • proceedings in case of discrepancies in statistics are conducted in case of a discrepancy of more than n% (under the contract). The comparison is based on the number of impressions shown (sent burl or nurl). Accordingly to statistics are compared by the number of impressions shown.

The volume of bid requests sent:

  • SSP reduces RPS for DSP that have many timeouts. If the number of timeouts count is greater than 5000 for 10 seconds for each instance, SSP completely stops sending bid requests, queries stop at all.

Integration process

Follow these steps for connecting a new DSP in the MGID system:

  1. The client acquaints with this document, if it is necessary specifies additional clarifying questions and confirms the readiness of the work under the described scheme
  2. The client provides prepared endpoint
  3. The client replenishes the account in the MGID system
  4. To verify the correctness of technical integration, tests are performed on small amounts of traffic (before starting tests of the query-response validation DSP must report the start of testing)
  5. The statistics of the viewable impressions of SSP and DSP checks during the test
  6. In the case of discrepancies, MGID provides a list of all called BURLs / NURLs so that the DSP can identify the problem and repeat steps 4 and 6
  7. Customer confirms readiness to launch
  8. A full-fledged launch for all traffic, which the client has chosen in pre-targeting, is conducted.

BidRequest

Description of supported parameters

bidrequest: objects and parameters

Parameter Type Description
id string; always Unique Request ID
tmax integer; default 150 ms The maximum response time from the DSP
imp object array; always An array of objects consisting of imp.
site object; always Site info
device object; always This object provides information pertaining to the device through which the user is interacting.
at integer; default 1 First price auction is on
user object; always Details via a User object about the human user of the device; the advertising audience.
cur string; array Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.
bcat string; array Blocked advertiser categories using the IAB content categories.
ext object Used to extend query parameters

source: parameters

Parameter TYPE DESCRIPTION
pchain string;
recommended
Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.

device: parameters

Parameter Type Description
dnt integer; always Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
devicetype integer The general type of device.
geo.country string Country code using ISO-3166-1-alpha-3
language string Browser language using ISO-639-1-alpha-2
js integer Support for JavaScript, where 0 = no, 1 = yes.
ua string; always Browser user agent string
ip string; always IPv4 address closest to device.
os string Device operating system

user: parameters

Parameter Type Description
id string; always MGID User ID
buyerid string; sometimes User ID in the partner system. If there is no cookiematching sends empty.
buyeruid string; sometimes User ID in the partner system. If there is no cookiematching sends empty.
ext object Used to extend query parameters

Note: buyerid equals buyeruid

user.ext: parameters

Parameter Type Description
pageview_number integer The number of user pageviews per one session
eids object Only for native request. Contains:
"eids": [{
"source": "adserver.org",
"uids": [{
"id": "uid123", #TradeDesk Unified ID
"ext": {
"rtiPartner": "TDID" #outgoing name
}
}],
 "source": "liveramp.com",
   "uids": [{
   "id": "uid123", #TradeDesk Unified ID
   }], 
}]

where:

eids.source - adserver.org / liveramp.com
eids.uids.id - TradeDesk Unified ID 
eids.uids.ext.rtiPartner - outgoing name

ext: parameters

Parameter Type Description
ad_types array; custom Custom categories based on the MPAA rating system.
landing_types array; custom Valid landing type in the format ["pg", "r", "nc17"]
imgSizeId integer; custom Internally the system's image size id, the image dimensions are also transferred in the corresponding fields hmin, wmin.
category integer; custom id of the site category by the MGID internal classification.

site: parameters

Parameter Type Description
id string; always Exchange-specific site ID.
name string;sometimes Site name
ref string; sometimes Referrer URL that caused navigation to the current page.
domain string; sometimes Domain of the site.
page string; sometimes URL of the page from which the request came
cat string array; sometimes Array of IAB content categories of the site
publisher.id string; always Exchange-specific publisher ID.
publisher.name string; sometimes Publisher name (may be aliased at the publisher’s request).
ext object Used to extend query parameters

site.ext: parameters

Parameter Type Description
traffic_source string;custom Traffic source
traffic_type string;custom Traffic type

imp: objects and parameters

Parameter Type Description
id string; always A unique identifier for this impression within the context
instl integer; default 0 1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid string Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer
native object; Required if Native Ad is intended
banner object; Required if Banner Ad is intended
bidfloor float; sometimes; default 0 Minimum CPM bid.
secure integer HTTPS URL 0 = HTTP, 1 = HTTPS

Notes: imp.bidfloor the field passed in the request is the amount of bidfloor places on the informer

native: objects and parameters

Parameter Type Description
request string; always Request payload complying with the Native Ad Specification.
ver string; always Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing
battr integer array Blocked creative attributes.

banner: objects and parameters

Parameter Type Description
id string; Unique identifier for this banner object.
w integer Exact width in device independent pixels (DIPS)
h integer Exact height in device independent pixels (DIPS)

request: parameters

Parameter Type Description
ver optional; string Version of the Native Markup version in use
plcmtcnt optional; integer; default 1 The number of identical placements in this template.
plcmttype optional; integer The format of the ad unit.
assets required; array of objects Array of objects. Each bet must match the specified conditions in this array.

assets: parameters

Parameter Type Description
id required; int Unique asset ID, assigned by exchange. Typically a counter for the array.
required optional; int; default 0 if = 1 - asset is required (the bet will not be accepted without filling it)
title optional; object Text object
img optional; object Image object
data optional; object Data object for brand name, description, ratings, prices etc.

Note: Each asset can consist of only one object title | img | data

title: parameters

Parameter Type Description
len required; integer Maximum length of the text in the title element.

img: parameters

Parameter Type Description
type optional; integer Image ID
w optional; integer Image width in pixels
wmin recommended; integer Minimum image width in pixels
h optional; integer Image height in pixels
hmin recommended; integer Minimum image height in pixels
mimes optional; array of strings; default All types List of supported MIME content types.

data: parameters

Parameter Type Description
type required; integer Item Type Id
len optional; integer Maximum number of characters of the object

BidRequest example

Native

{
"id":"0b95904b-38e5-11e8-9ae2-141877676018",
"tmax":150,
"at":1,
"device":{
"dnt":0,
"devicetype":2,
"js":1,
"ip":"36.76.94.171",
"os":"iOS",
"ua":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36",
"language":"en",
"geo":{
"country":"IDN"
}
},
"user":{
"id":"h6cOQQM5nUC0",
"buyerid":"",
"buyeruid":"",
"ext":{
        "eids": [{
  "source": "adserver.org",
  "uids": [{
    "id": "uid123", #TradeDesk Unified ID
    "ext": {
      "rtiPartner": "TDID" #outgoing name
     }
 }],
  "source": "liveramp.com",
  "uids": [{
   "id": "uid123", #TradeDesk Unified ID
 }],
}],
"pageview_number": 2,
}
},
"ext":{
"ad_types":[
"pg",
"r",
"nc17",
"nsfw"
],
"imgSizeId":19,
"category":101
},
"site":{
"id":"5646077",
"domain":"example.com",
"page":"http://example.com/",
"ref":"http://example.com/example?page=2",
"name":"example.com",
"cat":[ "IAB1" ],
"publisher":{
"id":"284527",
"name":"example.com"
}
},
"cur":[
"USD"
],
"bcat":[
"IAB13",
"IAB13-7",
"IAB18",
"IAB19"
],
"imp":[
{
"id":"1",
"bidfloor":0.09382198952879581,
"instl":0,
"secure":0,
"tagid":"835911",
"native":{
"request":"{\"ver\":\"1.1\",\"plcmtcnt\":4,\"plcmttype\":2,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"img\":{\"wmin\":492,\"hmin\":328,\"type\":3,\"mimes\":[\"image/jpeg\",\"image/jpg\",\"image/png\"]}},{\"id\":3,\"required\":0,\"data\":{\"type\":2,\"len\":75}},{\"id\":4,\"required\":0,\"data\":{\"type\":6}},{\"id\":5,\"required\":0,\"data\":{\"type\":7}},{\"id\":6,\"required\":0,\"data\":{\"type\":11}}]}\n",
"ver":"1.1",
"battr":[
1,
2,
3,
4,
5,
6,
8,
9,
10,
14
]
}
}
],
"source":{
"pchain":"d4c29acad76ce94f:5651930"
}
}

 

Banner

{
"id":"9f6f2cd6-d12c-11e8-aa98-246e96c2aeb2",
"tmax":150,
"at":1,
"device":{
"dnt":0,
"devicetype":2,
"js":1,
"ip":"113.160.142.178",
"os":"iOS",
"ua":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"language":"vi",
"geo":{
"country":"VNM"
}
},
"user":{
"id":"i6cUg3WiSxhh",
"buyerid":"",
"buyeruid":"",
"gender":"",
"yob":0,
"ext":{
"pageview_number": 2
}
},
"ext":{
"ad_types":[
"pg",
"r",
"nc17",
"nsfw"
],
"imgSizeId":19,
"category":145,
"informerId":87107,
"subid":"5651930_0"
},
"site":{
"id":"5651930",
"domain":"example.net",
"page":"http://example.net/dantri.html",
"ref":"https://www.google.com.vn/",
"name":"example.net",
"publisher":{
"id":"189470",
"name":"example.net"
},
"cat":[
"IAB1"
]
},
"publisher":{

},
"cur":[
"USD"
],
"imp":[
{
"id":"1",
"bidfloor":0.14011511111111108,
"instl":0,
"secure":1,
"tagid":"835911",
"banner":{
"id":"",
"w":300,
"h":250
}
}
],
"source":{
"pchain":"d4c29acad76ce94f:5651930"
}
}

 

Native-push

{
"id": "42cd21cb-f882-11e8-b79c-246e96c2aeb2",
"tmax": 150,
"at": 1,
"device": {
"dnt": 0,
"devicetype": 4,
"js": 1,
"ip": "31.173.83.243",
"ua": "Mozilla/5.0 (Linux; Android 8.0.0; SM-J330F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Mobile Safari/537.36",
"language": "ru",
"geo": {
"country": "RUS"
}
},
"user": {
"id": "5b759b5c6a4278993c107fb8",
"ext": {
"pageview_number": 1
}
},
"ext": {
"ad_types": [
"pg",
"r",
"nc17",
"nsfw"
],
"imgSizeId": 19,
"category": 0,
"informerId": 6650,
"subid": "5714200_0"
},
"site": {
"id": "5714200",
"domain": "example.com",
"name": "example.com",
"publisher": {
"id": "101924",
"name": "example.com"
}
},
"publisher": {

},
"cur": [
"USD"
],
"bcat": [
"IAB23",
"IAB24",
"IAB25",
"IAB26",
"IAB9-5",
"IAB9-7",
"IAB9-30"
],
"imp": [
{
"id": "1",
"bidfloor": 0.008473298429319372,
"instl": 0,
"secure": 1,
"tagid":"835911",
"native": {
"request": "{\"ver\":\"1.1\",\"plcmtcnt\":1,\"plcmttype\":4,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":75}},{\"id\":2,\"required\":1,\"img\":{\"wmin\":492,\"hmin\":328,\"type\":3,\"mimes\":[\"image/jpeg\",\"image/jpg\",\"image/png\"]}},{\"id\":3,\"required\":0,\"data\":{\"type\":2,\"len\":75}},{\"id\":4,\"required\":0,\"data\":{\"type\":6}},{\"id\":5,\"required\":0,\"data\":{\"type\":7}},{\"id\":6,\"required\":0,\"data\":{\"type\":11}}]}\n",
"ver": "1.1",
"battr": [
1,
2,
3,
4,
5,
6,
8,
9,
10,
14
]
}
}
],
"source": {
"pchain": "d4c29acad76ce94f:5714200"
}
}

 

 

BidResponse

Description of supported parameters

Object: BidResponse

Parameter Type Description
id string; required ID of the bid request to which this is a response.
seatbid object array Array of seatbid objects; 1+ required if a bid is to be made.
cur string; default “USD” Bid currency using ISO-4217 alpha codes.

Object: SeatBid

Parameter Type Description
bid object array; required Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression.
group integer; default 0 0 = impressions can be won individually; 1 = impressions must be won or lost as a group.

Note: bets with the value "group = 1" are not accepted

Object: Bid

Parameter Type Description
id string; required Bidder generated bid ID to assist with logging/tracking.
impid string; required ID of the Imp object in the related bid request.
price float; required Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java).
nurl string; highly recommended Win notice URL called by the exchange on the bid wins event if BURL string is present in bid response.
If BURL is not present in bid response, NURL call occurs on the viewable impression event (the logic of BURL) and no auction win event is sent.
Substitution macros may be included in both the URL and optionally returned markup. Supported macroses:
  • ${AUCTION_PRICE}
  • ${AUCTION_ID}
  • ${AUCTION_BID_ID}
  • ${AUCTION_PLACE_NUMBER}
  • ${AUCTION_CURRENCY}
burl string; highly recommended Billing URL called on the impression’ was shown to an end-user event (viewable impression).
Substitution macros may be included in both the URL and optionally returned markup. Supported macroses:
  • ${AUCTION_PRICE}
  • ${AUCTION_ID}
  • ${AUCTION_BID_ID}
  • ${AUCTION_PLACE_NUMBER}
  • ${AUCTION_CURRENCY}
adm string Means of conveying ad markup in case the bid wins
crid string; required Creative ID to assist with ad quality checking.

Note: to participate in the auction bid.price should be more than bidfloor:

bid.price > imp.bidfloor

Native Markup Response Object (seatbid.bid.adm)

Parameter Type Description
ver optional string Version of the Native Markup version in use.
assets required array of objects List of native ad’s assets.
link required object Destination Link. This is default link object for the ad. Individual assets can also have a link object which applies if the asset is activated(clicked).
imptrackers optional array of strings Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers. Supported macroses:
  • ${AUCTION_PRICE}
  • ${AUCTION_ID}
  • ${AUCTION_BID_ID}
  • ${AUCTION_PLACE_NUMBER}
  • ${AUCTION_CURRENCY}

Banner Markup Response Object

Notes:

  • Must be valid XHTML.
  • Supported macroses:
    • ${AUCTION_PRICE}
    • ${AUCTION_ID}
    • ${AUCTION_BID_ID}
    • ${AUCTION_PLACE_NUMBER}
    • ${AUCTION_CURRENCY}

BidResponse example

Native

{
"id":"d76d6bc2-ccf1-4c13-a296-8830496d4c28",
"cur":"USD",
"seatbid":[
{
"group":0,
"bid":[
{
"id":"1",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app1\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext1\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad1.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext1\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
},
{
"id":"2",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app2\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext2\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad2.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext2\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
},
{
"id":"3",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app3\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext3\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad3.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext3\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
}
]
}
]
}

 

Here, the "adm" object contains an encrypted json that looks like this (only one "adm" object is given as an example):

{
"imptrackers":[
],
"ver":"1.1",
"link":{
"url":"deeplink://deeplink/url/into/app1"
},
"assets":[
{
"id":1,
"title":{
"text":"title text1"
}
},
{
"id":2,
"img":{
"url":"http: //cdn.mobad.com/ad1.png",
"w":64,
"h":64
}
},
{
"id":3,
"data":{
"value":"description text1"
}
},
{
"id":4,
"data":{
"value":"goods price"
}
},
{
"id":5,
"data":{
"value":"goods old price"
}
}
]
}

 

Banner

{
"id":"fd0f730c-d12c-11e8-aa98-246e96c2aeb2",
"bidid":"85a13a21362470440de13f5a5820834d",
"seatbid":[
{
"bid":[
{
"id":"256e8e0df1f027c471901e6de3abe121",
"w":300,
"h":250,
"impid":"1",
"price":1.1271,
"nurl":"https://us-e10.example.com/?action=nurl&auction=${AUCTION_PRICE}&uniq=17773f575597e2a523e",
"burl":"https://us-e10.example.com/?action=burl&auction=${AUCTION_PRICE}&uniq=17773f575597e2a523e",
"adm":"<script type='text/javascript'>var site = '9db5e526900d'; </script>\r\n<script type='text/javascript' src=\"https://s3.example.com/6eda-4955-994c-992fb/general.js\"></script><img src='https://us-e-node14.example.com/?tpw=i&spr=1.28959&dp=39_e25f791c51cc62a99878ab368d54c9ab&t=bn&hash=967d0f6cd0aabb9ad3d1e8850d600e7b' border='0' width='1' height='1'><script async src='https://us.example.com/setck?p=b02fe53b2efd4bf0d8f581865a26d046'></script><img src=\"https://us-e10.example.com/?action=impression&auction=${AUCTION_PRICE}&uniq=17773f575597e2a523e\" border=\"0\" width=\"1\" height=\"1\">",
"adomain":[
"example.com"
],
"cat":[
"IAB1",
"IAB9"
],
"attr":[
4
],
"adid":"1017c9590a27",
"iurl":"http://us-e10.example.com/?action=iurl_&uniq=1017c9590a27",
"cid":"39_ccb3afd6f-992a-4165-81dc-fdb4f|291",
"crid":"39_rcb3afd6f-992a-4165-81dc-fdb4f|291"
}
],
"seat":"291"
}
],
"cur":"USD"
}

 

Native-push

{
"id":"d76d6bc2-ccf1-4c13-a296-8830496d4c28",
"cur":"USD",
"seatbid":[
{
"group":0,
"bid":[
{
"id":"1",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app1\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext1\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad1.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext1\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
},
{
"id":"2",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app2\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext2\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad2.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext2\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
},
{
"id":"3",
"impid":"1",
"crid":"3425d6f",
"price":10,
"nurl":"https://nurl",
"burl":"https://burl",
"adm":"{\"imptrackers\":[],\"ver\":"1.1",\"link\":{\"url\":\"deeplink://deeplink/url/into/app3\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"titletext3\"}},{\"id\":2,\"data\":{\"value\":\"5\"},\"img\":{\"url\":\"https://cdn.mobad.com/ad3.png\",\"w\":64,\"h\":64}},{\"id\":3,\"data\":{\"value\":\"descriptiontext3\"}},{\"id\":4,\"data\":{\"value\":\"goodsprice\"}},{\"id\":5,\"data\":{\"value\":\"goodsoldprice\"}}]}"
}
]
}
]
}

 

Targeting settings of advertising campaign

To be sure that MGID sends you the most suitable queries, you can set up pre-targeting in order to receive requests only for impressions that match the selected criteria. The following types of pre-targeting are available in the system:

  • by geo (countries and regions)
  • by device type and operating system
  • by browser
  • by theme of advertising platform

 

Cookie matching

MGID SSP supports matching storing on the SSP side and the DSP initiation by default. For matched users, both SSP UID and DSP UID will be sent in the fields bidRequest.user.id and bidRequest.user.buyeruid (find more here) . If user is new, there only SSP UID (bidRequest.user.id) will send.

For DSP-initiated-matching, SSP provides URL:

http(s)://cm.mgid.com/m?cdsp=XXXX&c=YYYY&adu=ZZZZ

where:

  • XXXX – Pixel ID in the MGID system (to get the ID contact the tech. account manager)
  • YYYY – user identifier in the DSP partner system (must not contain special characters - all special characters must be encoded (urlencode))
  • ZZZZ –  matching URL can redirect to the URL specified by the DSP. URL must be specified in the urlencoded-form in the parameter. Sets by prior arrangement, is disabled by default. The adu protocol must match the protocol of the original matching request.

 

Bidding recommendations

For effective buying, please follow this recommendations:

  1. Set up pre-targeting correctly in order to receive requests only for needed impressions and do not filter extra impressions on the DSP side.
  2. Note that bidfloor is set for one teaser placement.
  3. To increase the probability of winning it is recommended to bet on 20-30% higher than bidfloor.
  4. If the DSP uses user data for advertising, it is necessary to set up cookie matching.
  5. MGID recommends to analyze and optimize bids, taking into account the following parameters in the bid request:
    1. site.id
    2. devicetype
    3. ua
    4. country
    5. user.ext.pageview_number

 

Appendix A  ext.ad_types

Type Description
PG No suggestive material of any kind. This includes images of people showing too much skin (no cleavage, stomach, or above the knee) and provocative language. No mature topics, highly controversial issues, or depictions of any violence.
R Creative content includes sexual topics and non-explicit suggestive imagery, as well as violence in news or entertainment media. Creative content may include humorous material restricted to an older audience. Parental guidance is suggested for a younger audience.
NC17 Subject matter may be more controversial with strange, odd or peculiar imagery. This rating does not include creative content relating to sexual subject matters. Bizarre stories, non-fictional and fictional depictions of people may be included here.
NSFW Creative content may be sexual in nature, sensational, shocking, or outrageous. Creative content does not contain nudity, pornography, erotica, or explicit sex.

More about ad_types at content guidelines.

 

Appendix B  ext.imgsizeid

imgsizeid width height
0 0 0
1 45 45
2 75 75
3 60 60
4 120 120
5 200 200
6 80 53
7 100 75
8 140 140
9 90 90
10 100 60
11 170 90
12 300 200
13 150 100
14 370 200
15 180 120
16 260 170
17 200 150
18 328 328
19 492 328
23 300 260

 

Appendix C  ext.category

category name
100 Books and Literature
101 Comics and Graphic Novels
102 Reading Online
103 Movies
104 Music and Audio
105 Video Gaming
106 Automotive
107 Business and Finance
108 Careers
109 Education
110 Healthy Living
111 Hobbies and Interests
112 Arts and Crafts
113 Humor
114 Home and Garden
115 Family and Relationships
116 Parenting
117 Relationships
118 Dating
119 Fine Art
120 Food and Drink
121 Medical Health
122 News and Politics
123 News
124 Politics
125 Weather
126 Pets
127 Religion and Spirituality
128 Astrology
129 Science
130 Sports
131 Style and Fashion
132 Beauty
133 Fashion Trends
134 Technology and Computing
135 Computing
136 Computer Software and Applications
137 Internet
138 Consumer Electronics
139 Data Storage and Warehousing
140 Travel
141 Pop Culture
142 Events and Attractions
143 Non-Standard Content
144 Uncategorized
145 Entertainment
146 Lifestyle
147 Shopping
148 Television

 

Appendix D imp.native.request.plcmttype

plcmttype placement examples description
2 in article, header In the atomic unit of the content - IE in the article page or single image page
3 sidebar Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc.
4 under article Recommendation widget, most commonly presented below the article content.

 

Appendix E Content Categories

category name
IAB1 Arts & Entertainment
IAB1-1 Books & Literature
IAB1-2 Celebrity Fan/Gossip
IAB1-3 Fine Art
IAB1-4 Humor
IAB1-5 Movies
IAB1-6 Music
IAB1-7 Television
IAB2 Automotive
IAB2-1 Auto Parts
IAB2-2 Auto Repair
IAB2-3 Buying/Selling Cars
IAB2-4 Car Culture
IAB2-5 Certified Pre-Owned
IAB2-6 Convertible
IAB2-7 Coupe
IAB2-8 Crossover
IAB2-9 Diesel
IAB2-10 Electric Vehicle
IAB2-11 Hatchback
IAB2-12 Hybrid
IAB2-13 Luxury
IAB2-14 Minivan
IAB2-15 Motorcycles
IAB2-16 Off-Road Vehicles
IAB2-17 Performance Vehicles
IAB2-18 Pickup
IAB2-19 Road-Side Assistance
IAB2-20 Sedan
IAB2-21 Trucks & Accessories
IAB2-22 Vintage Cars
IAB2-23 Wagon
IAB3 Business
IAB3-1 Advertising
IAB3-2 Agriculture
IAB3-3 Biotech/Biomedical
IAB3-4 Business Software
IAB3-5 Construction
IAB3-6 Forestry
IAB3-7 Government
IAB3-8 Green Solutions
IAB3-9 Human Resources
IAB3-10 Logistics
IAB3-11 Marketing
IAB3-12 Metals
IAB4 Careers
IAB4-1 Career Planning
IAB4-2 College
IAB4-3 Financial Aid
IAB4-4 Job Fairs
IAB4-5 Job Search
IAB4-6 Resume Writing/Advice
IAB4-7 Nursing
IAB4-8 Scholarships
IAB4-9 Telecommuting
IAB4-10 U.S. Military
IAB4-11 Career Advice
IAB5 Education
IAB5-1 7-12 Education
IAB5-2 Adult Education
IAB5-3 Art History
IAB5-4 College Administration
IAB5-5 College Life
IAB5-6 Distance Learning
IAB5-7 English as a 2nd Language
IAB5-8 Language Learning
IAB5-9 Graduate School
IAB5-10 Homeschooling
IAB5-11 Homework/Study Tips
IAB5-12 K-6 Educators
IAB5-13 Private School
IAB5-14 Special Education
IAB5-15 Studying Business
IAB6 Family & Parenting
IAB6-1 Adoption
IAB6-2 Babies & Toddlers
IAB6-3 Daycare/Pre School
IAB6-4 Family Internet
IAB6-5 Parenting - K-6 Kids
IAB6-6 Parenting teens
IAB6-7 Pregnancy
IAB6-8 Special Needs Kids
IAB6-9 Eldercare
IAB7 Health & Fitness
IAB7-1 Exercise
IAB7-2 ADD
IAB7-3 AIDS/HIV
IAB7-4 Allergies
IAB7-5 Alternative Medicine
IAB7-6 Arthritis
IAB7-7 Asthma
IAB7-8 Autism/PDD
IAB7-9 Bipolar Disorder
IAB7-10 Brain Tumor
IAB7-11 Cancer
IAB7-12 Cholesterol
IAB7-13 Chronic Fatigue Syndrome
IAB7-14 Chronic Pain
IAB7-15 Cold & Flu
IAB7-16 Deafness
IAB7-17 Dental Care
IAB7-18 Depression
IAB7-19 Dermatology
IAB7-20 Diabetes
IAB7-21 Epilepsy
IAB7-22 GERD/Acid Reflux
IAB7-23 Headaches/Migraines
IAB7-24 Heart Disease
IAB7-25 Herbs for Health
IAB7-26 Holistic Healing
IAB7-27 IBS/Crohn’s Disease
IAB7-28 Incest/Abuse Support
IAB7-29 Incontinence
IAB7-30 Infertility
IAB7-31 Men’s Health
IAB7-32 Nutrition
IAB7-33 Orthopedics
IAB7-34 Panic/Anxiety Disorders
IAB7-35 Pediatrics
IAB7-36 Physical Therapy
IAB7-37 Psychology/Psychiatry
IAB7-38 Senior Health
IAB7-39 Sexuality
IAB7-40 Sleep Disorders
IAB7-41 Smoking Cessation
IAB7-42 Substance Abuse
IAB7-43 Thyroid Disease
IAB7-44 Weight Loss
IAB7-45 Women's Health
IAB8 Food & Drink
IAB8-1 American Cuisine
IAB8-2 Barbecues & Grilling
IAB8-3 Cajun/Creole
IAB8-4 Chinese Cuisine
IAB8-5 Cocktails/Beer
IAB8-6 Coffee/Tea
IAB8-7 Cuisine-Specific
IAB8-8 Desserts & Baking
IAB8-9 Dining Out
IAB8-10 Food Allergies
IAB8-11 French Cuisine
IAB8-12 Health/Low-Fat Cooking
IAB8-13 Italian Cuisine
IAB8-14 Japanese Cuisine
IAB8-15 Mexican Cuisine
IAB8-16 Vegan
IAB8-17 Vegetarian
IAB8-18 Wine
IAB9 Hobbies & Interests
IAB9-1 Art/Technology
IAB9-2 Arts & Crafts
IAB9-3 Beadwork
IAB9-4 Bird-Watching
IAB9-5 Board Games/Puzzles
IAB9-6 Candle & Soap Making
IAB9-7 Card Games
IAB9-8 Chess
IAB9-9 Cigars
IAB9-10 Collecting
IAB9-11 Comic Books
IAB9-12 Drawing/Sketching
IAB9-13 Freelance Writing
IAB9-14 Genealogy
IAB9-15 Getting Published
IAB9-16 Guitar
IAB9-17 Home Recording
IAB9-18 Investors & Patents
IAB9-19 Jewelry Making
IAB9-20 Magic & Illusion
IAB9-21 Needlework
IAB9-22 Painting
IAB9-23 Photography
IAB9-24 Radio
IAB9-25 Roleplaying Games
IAB9-26 Sci-Fi & Fantasy
IAB9-27 Scrapbooking
IAB9-28 Screenwriting
IAB9-29 Stamps & Coins
IAB9-30 Video & Computer Games
IAB9-31 Woodworking
IAB10 Home & Garden
IAB10-1 Appliances
IAB10-2 Entertaining
IAB10-3 Environmental Safety
IAB10-4 Gardening
IAB10-5 Home Repair
IAB10-6 Home Theater
IAB10-7 Interior Decorating
IAB10-8 Landscaping
IAB10-9 Remodeling & Construction
IAB11 Law, Government, & Politics
IAB11-1 Immigration
IAB11-2 Legal Issues
IAB11-3 U.S. Government Resources
IAB11-4 Politics
IAB11-5 Commentary
IAB12 News
IAB12-1 International News
IAB12-2 National News
IAB12-3 Local News
IAB13 Personal Finance
IAB13-1 Beginning Investing
IAB13-2 Credit/Debt & Loans
IAB13-3 Financial News
IAB13-4 Financial Planning
IAB13-5 Hedge Fund
IAB13-6 Insurance
IAB13-7 Investing
IAB13-8 Mutual Funds
IAB13-9 Options
IAB13-10 Retirement Planning
IAB13-11 Stocks
IAB13-12 Tax Planning
IAB14 Society
IAB14-1 Dating
IAB14-2 Divorce Support
IAB14-3 Gay Life
IAB14-4 Marriage
IAB14-5 Senior Living
IAB14-6 Teens
IAB14-7 Weddings
IAB14-8 Ethnic Specific
IAB15 Science
IAB15-1 Astrology
IAB15-2 Biology
IAB15-3 Chemistry
IAB15-4 Geology
IAB15-5 Paranormal Phenomena
IAB15-6 Physics
IAB15-7 Space/Astronomy
IAB15-8 Geography
IAB15-9 Botany
IAB15-10 Weather
IAB16 Pets
IAB16-1 Aquariums
IAB16-2 Birds
IAB16-3 Cats
IAB16-4 Dogs
IAB16-5 Large Animals
IAB16-6 Reptiles
IAB16-7 Veterinary Medicine
IAB17 Sports
IAB17-1 Auto Racing
IAB17-2 Baseball
IAB17-3 Bicycling
IAB17-4 Bodybuilding
IAB17-5 Boxing
IAB17-6 Canoeing/Kayaking
IAB17-7 Cheerleading
IAB17-8 Climbing
IAB17-9 Cricket
IAB17-10 Figure Skating
IAB17-11 Fly Fishing
IAB17-12 Football
IAB17-13 Freshwater Fishing
IAB17-14 Game & Fish
IAB17-15 Golf
IAB17-16 Horse Racing
IAB17-17 Horses
IAB17-18 Hunting/Shooting
IAB17-19 Inline Skating
IAB17-20 Martial Arts
IAB17-21 Mountain Biking
IAB17-22 NASCAR Racing
IAB17-23 Olympics
IAB17-24 Paintball
IAB17-25 Power & Motorcycles
IAB17-26 Pro Basketball
IAB17-27 Pro Ice Hockey
IAB17-28 Rodeo
IAB17-29 Rugby
IAB17-30 Running/Jogging
IAB17-31 Sailing
IAB17-32 Saltwater Fishing
IAB17-33 Scuba Diving
IAB17-34 Skateboarding
IAB17-35 Skiing
IAB17-36 Snowboarding
IAB17-37 Surfing/Body-Boarding
IAB17-38 Swimming
IAB17-39 Table Tennis/Ping-Pong
IAB17-40 Tennis
IAB17-41 Volleyball
IAB17-42 Walking
IAB17-43 Waterski/Wakeboard
IAB17-44 World Soccer
IAB18 Style & Fashion
IAB18-1 Beauty
IAB18-2 Body Art
IAB18-3 Fashion
IAB18-4 Jewelry
IAB18-5 Clothing
IAB18-6 Accessories
IAB19 Technology & Computing
IAB19-1 3-D Graphics
IAB19-2 Animation
IAB19-3 Antivirus Software
IAB19-4 C/C++
IAB19-5 Cameras & Camcorders
IAB19-6 Cell Phones
IAB19-7 Computer Certification
IAB19-8 Computer Networking
IAB19-9 Computer Peripherals
IAB19-10 Computer Reviews
IAB19-11 Data Centers
IAB19-12 Databases
IAB19-13 Desktop Publishing
IAB19-14 Desktop Video
IAB19-15 Email
IAB19-16 Graphics Software
IAB19-17 Home Video/DVD
IAB19-18 Internet Technology
IAB19-19 Java
IAB19-20 JavaScript
IAB19-21 Mac Support
IAB19-22 MP3/MIDI
IAB19-23 Net Conferencing
IAB19-24 Net for Beginners
IAB19-25 Network Security
IAB19-26 Palmtops/PDAs
IAB19-27 PC Support
IAB19-28 Portable
IAB19-29 Entertainment
IAB19-30 Shareware/Freeware
IAB19-31 Unix
IAB19-32 Visual Basic
IAB19-33 Web Clip Art
IAB19-34 Web Design/HTML
IAB19-35 Web Search
IAB19-36 Windows
IAB20 Travel
IAB20-1 Adventure Travel
IAB20-2 Africa
IAB20-3 Air Travel
IAB20-4 Australia & New Zealand
IAB20-5 Bed & Breakfasts
IAB20-6 Budget Travel
IAB20-7 Business Travel
IAB20-8 By US Locale
IAB20-9 Camping
IAB20-10 Canada
IAB20-11 Caribbean
IAB20-12 Cruises
IAB20-13 Eastern Europe
IAB20-14 Europe
IAB20-15 France
IAB20-16 Greece
IAB20-17 Honeymoons/Getaways
IAB20-18 Hotels
IAB20-19 Italy
IAB20-20 Japan
IAB20-21 Mexico & Central America
IAB20-22 National Parks
IAB20-23 South America
IAB20-24 Spas
IAB20-25 Theme Parks
IAB20-26 Traveling with Kids
IAB20-27 United Kingdom
IAB21 Real Estate
IAB21-1 Apartments
IAB21-2 Architects
IAB21-3 Buying/Selling Homes
IAB22 Shopping
IAB22-1 Contests & Freebies
IAB22-2 Couponing
IAB22-3 Comparison
IAB22-4 Engines
IAB23 Religion & Spirituality
IAB23-1 Alternative Religions
IAB23-2 Atheism/Agnosticism
IAB23-3 Buddhism
IAB23-4 Catholicism
IAB23-5 Christianity
IAB23-6 Hinduism
IAB23-7 Islam
IAB23-8 Judaism
IAB23-9 Latter-Day Saints
IAB23-10 Pagan/Wiccan
IAB24 Uncategorized
IAB25 Non-Standard Content
IAB25-1 Unmoderated UGC
IAB25-2 Extreme Graphic/Explicit Violence
IAB25-3 Pornography
IAB25-4 Profane Content
IAB25-5 Hate Content
IAB25-6 Under Construction
IAB25-7 Incentivized
IAB26 Illegal Content
IAB26-1 Illegal Content
IAB26-2 Warez
IAB26-3 Spyware/Malware
IAB26-4 Copyright Infringement