OpenRTB Integration

Integration process for demand partners to participate in Chartboost Mediation

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 a server-side integration. Helium’s server side technology uses the OpenRTB 2.5 specification to conduct its first-price auctions. The demand partner’s SDK is fully integrated within the ecosystem and is allowed to function as it normally would without any modifications.


SDK Instructions

Publishers participating in Mediation need to integrate the Mediation’s SDK and the participating ad networks' SDKs. The Helium’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

AttributeTypeRequiredDescription
idstringyesA unique identifier referencing a particular bid request. This is generated by Chartboost Mediation.
impobject arrayyesAn array of impression objects that describe the ad placements available to bid on.
appobjectyesDetails via an App object (See: Object App) about the publisher’s app.
deviceobjectyesDetails via a Device object (See: Object Device) about the user’s device to which the impression will be delivered.
userobjectyesDetails via a User object (See: Object User) about the human user of the device; the advertising audience.
testintegeryesIndicator of test mode in which auctions are not billable, where 0=live mode (default), 1=test mode.
atintegeryesAuction type, where 1=First Price, 2=Second Price Plus. Default 1 for Mediation.
tmaxintegeryesMaximum time in milliseconds allows for bids to be received including Internet latency to avoid timeout (default 800ms).
curstring arrayyesList of supported currencies. Currently only “USD”.
bcatstring arrayyesBlocked advertiser categories using the IAB content categories.
badvstring arrayyesBlock list of advertisers by their domains
bappstring arrayyesBlock list of applications by their platform-specific application identifiers. Bundle or package names for Android and iTunes store IDs for iOS.
regsobjectyesA Regs object (See: Object Regs) that specifies any industry, legal, or governmental regulations in force for this request (COPPA, GDPR etc).
extobjectyesPlaceholder for custom extensions to OpenRTB.

Object: Imp

AttributeTypeRequiredDescription
idstringyesA unique identifier for this impression within the context of the bid request. It will start at one and increment with each additional imp object.
bannerobjectyesA Banner object (See: Object Banner), this impression is offered as a banner ad opportunity.
videoobjectyesA Video object (See: Object Video); required if this
impression is offered as a video ad opportunity.
displaymanagerstringyesDisplay SDK name (Demand SDK)
displaymanagerverstringyesDisplay SDK version
instlintegeryes1=the ad is interstitial or full screen, 0=not interstitial.
tagidstringyesPlacement id or tag.
bidfloorfloatyesMinimum bid for this impression expressed in CPM. The default currency is “USD”.
secureintegeryesFlag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. The default is 1.
extobjectyesPlaceholder for custom extensions to OpenRTB.

Object: Banner

AttributeTypeRequiredDescription
wintegeryesExact width in device independent pixels (DIPS). Interstitial sizes include 320 or 480 for Phones, 768 or 1024 for Tablets. Banner sizes include 300, 320 and 728.
hintegeryesExact height in device independent pixels (DIPS). Interstitial sizes include 480 or 320 for Phones, 1024 or 768 for Tablets. Banner sizes include 250, 50 and 90.
btypeinteger arrayyesBlocked banner ad types. Refer to List 5.2 on IAB OpenRTB 2.5 specs for more details. The default value is 4.
battrinteger arrayyesBlocked creative attributes. Refer to List 5.3 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2, 6, 7.
posintegeryesAd position on screen. Refer to List 5.4 on IAB OpenRTB 2.5 specs for more details. The default value is 7.
topframeintegeryesIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes. The default value is 1.
apiinteger arrayyesList of supported API frameworks for this impression. Refer to List 5.6 on IAB OpenRTB 2.5 specs for more details. The default value is 3.
extobjectyesPlaceholder for custom extensions to OpenRTB.

Object: Video

AttributeTypeRequiredDescription
mimesstring arrayyesContent MIME types supported. The default value is video/mp4.
mindurationintegeryesMinimum video ad duration in seconds. The default value is 6.
maxdurationintegeryesMaximum video ad duration in seconds. The default value is 30.
protocolinteger arrayyesArray of supported video bid response
protocols. Refer to List 5.8 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2, 3, 5, 6.
wintegeryesWidth of the video player in device independent pixels (DIPS). Interstitial sizes include 320 or 480 for Phones, 1024 or 768 for Tablets.
hintegeryesHeight of the video player in device independent pixels (DIPS). Interstitial sizes include 320 or 480 for Phones, 1024 or 768 for Tablets.
placementintegeryesPlacement type for the impression. Refer to List 5.9 on IAB OpenRTB 2.5 specs for more details. The default value is 5.
linearityintegeryesIndicates if the impression must be linear, nonlinear, etc. Refer to List 5.7 on IAB OpenRTB 2.5 specs for more details. The default value is 1.
skipintegeryesIndicates if the player will allow the video to be skipped, where 0=no, 1=yes.
deliveryinteger arrayyesSupported delivery methods (e.g., streaming, progressive). Refer to List 5.15 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2.
posintegeryesAd position on screen. Refer to List 5.4 on IAB OpenRTB 2.5 specs for more details. The default value is 7.
companiontypeInteger arrayyesSupported VAST companion ad types. Refer to List 5.14 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2.
extobjectyesPlaceholder for custom extensions to OpenRTB.

Object: App

AttributeTypeRequiredDescription
idstringyesEach demand partner specific publisher app ID
namestringyesApp name
bundlestringyesApp bundle ID
storeurlstringyesApp store URL for the publisher app
catstring arrayyesArray of IAB content categories of the app. Refer to List 5.1 on IAB OpenRTB 2.5 specs for more details. The default value is IAB9-30 for the mobile games on Mediation.
publisherobjectyesDetails about the Publisher (Section 4.6) of the app.

Object: Publisher

AttributeTypeRequiredDescription
idstringyesDemand partner specific publisher ID
namestringyesPublisher name

Object: Device

AttributeTypeRequiredDescription
uastringyesBrowser user agent string. e.g. (Mozilla/5.0 (iPad; CPU OS 10_0_1 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A403)
geoobjectyesGeo object (See: Object Geo) containing country, type, region, city, zip
lmtintegeryes“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0=tracking is unrestricted, 1=tracking must be limited per commercial guidelines
ipstringyesIPv4 address closest to device
devicetypeintegeryesThe general type of device. Refer to List 5.21 on IAB OpenRTB 2.5 specs for more details
makestringyesDevice make (e.g., “Apple”)
modelstringyesDevice model (e.g., “iPhone”)
osstringyesDevice operating system (e.g., “iOS”)
osvstringyesDevice operating system version (e.g., “3.1.2”)
hintegeryesPhysical height of the screen in pixels
wintegeryesPhysical width of the screen in pixels
pxratiofloatyesThe ratio of physical pixels to device independent pixels
languagestringyesBrowser language using ISO-639-1-alpha-2
carrierstringyesCarrier or ISP (e.g., “VERIZON”)
connectiontypeintegeryesNetwork connection type. Refer to List 5.22 on IAB OpenRTB 2.5 specs for more details
ifastringyesID sanctioned for advertiser use in the clear (i.e., not hashed)
ext.ifvstringnoID sanctioned for vendor use. Includes iOS IDFV and Android App Set ID. This ID only be used for frequency capping purposes

Object: Geo

AttributeTypeRequiredDescription
typeintegeryesSource of location data. Refer to List 5.20 on IAB OpenRTB 2.5 specs for more details. The default value is 2.
countrystringyesCountry code using ISO-3166-1-alpha-3
regionstringyesRegion code using ISO-3166-2; 2-letter state code if USA
citystringyesCity using United Nations Code for Trade & Transport Locations
zipstringyesZip or postal code

Object: User

AttributeTypeRequiredDescription
idstringyesA unique identifier for the user.
geoobjectyesGeo object (See: Object Geo) containing country, type, region, city, zip
ext.consentstringyesConsent string for GDPR

Object: Regs

AttributeTypeRequiredDescription
coppaintegeryesRequire Coppa Compliant Ad. (0=No, 1=Yes) Will be omitted if No.
us_privacystringyesCCPA related regulation information. See IAB’s USPrivacy page for supported string formats.
ext.gdprintegeryesSubject to GDPR Regulations (0=No, 1=Yes)

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 Helium. 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.