OpenRTB Integration

Introduction

Chartboost Mediation (formerly Helium) allows all demand sources to bid CPM prices in real-time and compete for available impression opportunities on participating publishers’ mobile apps. The integration process consists of an SDK and server-side integration. Mediation's server-side technology uses the OpenRTB 2.5 specification to conduct its first-price auctions.

---

SDK Instructions

Publishers participating in Chartboost Mediation need to integrate the Mediation’s SDK and the participating ad networks' SDKs. The Mediation’s SDK team will work with each ad network to develop SDK adapters.

When a winning bid is selected in the real-time auction, Mediation SDK will communicate to the winning ad network’s SDK via the custom adapter. The ad network’s SDK will then render the winning ads in a publisher’s mobile app.

---

OpenRTB

Chartboost Mediation uses the OpenRTB V 2.5 standard. See below for the full details.

Object: BidRequest

Object: Imp

Object: Banner

Object: Video

Object: App

Object: Publisher

Object: Device

Object: Geo

Object: User

Object: Regs

---

Bid Request and Bid Response Samples

Request Sample

Note: below is just a sample bid request. The Mediation team can work with each demand partner on some custom fields.

{
    "id": "9f62b4373cf9d57e2262e118ebef35b8ed19d529",
    "imp": [
        {
            "id": "9f62b4373cf9d57e2262e118ebef35b8ed19d529",
            "displaymanager": "AdNetwork-iOS-SDK",            
            "displaymanagerver": "1.1.1",            
            "instl": 1,
            "tagid": "408",
            "bidfloor": 0.5,
            "secure": 1,
            "video": {
                "mimes": [
                  "video/mp4"
                ],
                "minduration": 6,
                "maxduration": 30,
                "protocols": [
                  1,
                  2,
                  3,
                  5,
                  6, 
                ],
                "w": 320,
                "h": 480,
                "placement": 5,
                "linearity": 1,
                "skip": 1,
                "delivery": [
                  1,
                  2
                ],
                "pos": 7,
                "companiontype": [
                  1,
                  2
                ],
                "ext": {
                  "placementtype": "rewarded"
                }
            },
            "banner": {
                "w": 320,
                "h": 480,
                "btype": [
                  4
                ],
                "battr": [
                  1,
                  2,
                  6,
                  7
                ],
                "pos": 7,
                "topframe": 1,
                "api": [
                  3
                ],
                "ext": {
                  "placementtype": "rewarded",
                  "playableonly": true,
                  "allowscustomclosebutton": false
                }
            },
        }
    ],
    "app": {
      "id": "587e6e0543150f50c8c709f9",
      "name": "iOS test app",
      "bundle": "com.ios.test",
      "storeurl": "https://itunes.apple.com/xxxxx",
      "cat": [
        "IAB9-30"
      ],
      "publisher": {
        "id": "55c9071d43150f6c8b6bf1e4",
        "name": "iOS Test Publisher"
      },
      "ext": {
        "itunesid": "907000000"
      }
    },
    "device": {
        "lmt": 0,
        "ua": "Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403",
        "geo": {
          "type": 2,
          "country": "USA",
          "region": "CA",
          "city": "San Francisco",
          "zip": "94155"
        },
        "ip": "4.35.161.98",
        "devicetype": 4,
        “make”: “Apple”,
        "model": "iPhone9,3",
        "os": "iOS",
        "osv": "11.2.5",
        "h": 2008,
        "w": 1536,
        "language": "en",
        "carrier": "WIFI",
        "connectiontype": 2,
        "ifa": "EEEE9F4F-5121-7512-4B04-96A4AFFDBE07"
    },
    "regs": {
        "coppa": 0
    },
    "test": 0,
    "user": {
        "id": "1de9a4da-2266-11e8-b466-5530e43ff6b8",
        "geo": {
          "type": 2,
          "country": "USA",
          "region": "CA",
          "city": "San Francisco",
          "zip": "94155"
        }
      },
    "at": 1,
    "cur": [
        "USD"
    ],
    "tmax": 800,
    "bcat": [
"IAB2-3"
],
    "badv": [
       "badapps.com",
       "worseapps.com"
  ],
    "bapp": [
         "com.badapps.badapp"
  ]
}

Response Sample

Note: below is just a sample bid response. The Mediation team can work with each demand partner on the optional fields.

{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "cbrtb-512939461-320x5680.2625",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "9d554579-f21a-4f6f-a33e-42c41b09b206",
          "adomain": [
            "foobar.com"
          ],
          "bundle": "com.foobar.game",
          "id": "cbrtb-512939461-320x568-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "adm": "<div id='foobarad' style='background-color:black; position:relative; width:100%; height:100%;'><a href='https:\/\/c.foobar.com\/ads\/c.php?a=cbrtb&b=cbrtb-512939461-320x568&c=190d3bfd&d=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&ct=0&nb=1&gf=https%3A%2F%2Fcdn.foobar.com%2F88518%2FQ2_FIND_GET_testB_320x480_20161020_18_28_26.jpg&its=1486583763&f=96ebd0d524e12401190d3bfd02081156&ra=0U0..WSA.1.200O000P31100.0000000003B0U00000B0.A0&aid=7EEE44E2-EC2C-C266-4A64-AD1CADA1D062&campaignID=123160110&adgroupID=180589&adGroup=Twitter_iOS_Campaign+A_US&campaignCode=iOS_Campaign+A&defcpa=0&defcpc=0&appid=333903271&creativeID=ad4ee8cb&adType=StaticInterstitial&countrycode=US&ccimpid=X96142fe8497a5eb8888888802081156&accountid=2165&it=mi&inf=0&cg=CampaignA%26B-+Nerd&adType=StaticInterstitial&creativeID=ad4ee8cb'><img style='position:absolute;top: 0;left: 0;bottom: 0;right: 0;margin:auto; max-width:100%; max-height:100%' src='https:\/\/cdn.foobar.com\/88518\/Q2_FIND_GET_testB_320x480_20161020_18_28_26.jpg' ><\/a><\/div>",
          "ext": {
            "imptrackers":  "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ],
          }
        }
      ]
    }
  ]
}

---

Auction Dynamics

Chartboost Mediation runs first-price auctions. Each demand partner needs to return a valid bid response with a bid price within the timeout limit (default 800ms) in order to participate in the auction and compete for the available impression opportunity. The bid price should be not less than the bid floor price as indicated in the bid request. It is mandatory for demand partners to make hard bids on Mediation. After the bid responses are validated, the demand partner with the highest bid price will win the auction. When the impression is shown, the demand partner is subject to paying publishers based on the clearing price.

Mediation also supports win notification and loss notification.