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

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

source: parameters

device: parameters

user: parameters

Note: buyerid equals buyeruid

user.ext: parameters

"eids": [{
   "source": "adserver.org",
   "uids": [{
     "id": "uid123", #TradeDesk Unified ID
     "ext": {
        "rtiPartner": "TDID" #outgoing name
     }
   }],
   "source": "liveramp.com",
   "uids": [{
     "id": "uid123", #TradeDesk Unified ID
   }], 
}]

ext: parameters

site: parameters

site.ext: parameters

imp: objects and parameters

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

native: objects and parameters

banner: objects and parameters

request: parameters

assets: parameters

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

title: parameters

img: parameters

data: parameters

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

Object: SeatBid

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

Object: Bid

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

Native Markup Response Object (seatbid.bid.adm)

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

More about ad_types at content guidelines.

Appendix B  ext.imgsizeid

Appendix C  ext.category

Appendix D imp.native.request.plcmttype

Appendix E Content Categories