Partners

Mediation OpenRTB Integration

Chartboost Mediation (formerly Helium) uses the OpenRTB V 2.5 standard. See below for specific Chartboost Mediation details.

Object: BidRequest 🔗

Attribute Type Always Passed? Description
id string yes A unique identifier referencing a particular bid request. This is generated by Chartboost Mediation.
imp object array yes An array of impression objects that describe the ad placements available to bid on. (See: Object Imp)
app object yes Details via an App object (See: Object App) about the publisher’s app.
device object yes Details via a Device object (See: Object Device) about the user’s device to which the impression will be delivered.
user object yes Details via a User object (See: Object User) about the human user of the device; the advertising audience.
test integer no Indicator of test mode in which auctions are not billable, where 0=live mode (default), 1=test mode. Passed only if test=1.
at integer yes Auction type. Default 1 for Chartboost Mediation, where 1=First Price.
tmax integer yes Maximum time in milliseconds Chartboost Mediation allows for bids to be received including Internet latency to avoid timeout. (default: rewarded 2000ms, interstitial 2000ms, rewarded interstitial 2000ms, banner 1000ms, adaptive banner 1000ms).
cur string array yes List of supported currencies. Currently only “USD”.
bcat string array yes Blocked advertiser categories using the IAB content categories.
badv string array yes Block list of advertisers by their domains
bapp string array yes Block list of applications by their platform-specific application identifiers. Bundle or package names for Android and iTunes store IDs for iOS.
regs object yes A Regs object (See: Object Regs) that specifies any industry, legal, or governmental regulations in force for this request (COPPA, GDPR etc).
ext object yes Placeholder for custom extensions to OpenRTB.

Object: Imp 🔗

Attribute Type Always Passed? Description
id string yes A unique identifier for this impression within the context of the bid request. It will start at one and increment with each additional imp object.
banner object yes A Banner object (See: Object Banner), this impression is offered as a banner ad opportunity.
video object yes A Video object (See: Object Video); required if this impression is offered as a video ad opportunity.
displaymanager string yes Display SDK name (Demand SDK)
displaymanagerver string yes Display SDK version
instl integer yes 1=the ad is interstitial or full screen, 0=not interstitial.
tagid string yes Placement id or tag.
bidfloor float no Minimum bid for this impression expressed in CPM. The default currency is “USD”. Only passed if a floor price is set.
secure integer no Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. The default is 1.
ext object no Placeholder for custom extensions to OpenRTB.

Object: Banner 🔗

Attribute Type Always Passed? Description
w integer yes Exact 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.
h integer yes Exact 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.
btype integer array yes Blocked banner ad types. Refer to List 5.2 on IAB OpenRTB 2.5 specs for more details. The default value is 4 for Chartboost Mediation.
battr integer array yes Blocked creative attributes. Refer to List 5.3 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2, 6, 7 for Chartboost Mediation.
pos integer yes Ad position on screen. Refer to List 5.4 on IAB OpenRTB 2.5 specs for more details. The default value is 7 for Chartboost Mediation.
topframe integer yes Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes. The default value is 1 for Chartboost Mediation.
api integer array yes List 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 for Chartboost Mediation.
ext object yes Placeholder for custom extensions to OpenRTB.

Object: Video 🔗

Attribute Type Always Passed? Description
mimes string array yes Content MIME types supported. The default value is video/mp4.
minduration integer yes Minimum video ad duration in seconds. The default value is 6.
maxduration integer yes Maximum video ad duration in seconds. The default value is 30.
protocol integer array yes Array of supported video bid responseprotocols. Refer to List 5.8 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2, 3, 5, 6.
w integer yes Width of the video player in device independent pixels (DIPS). Interstitial sizes include 320 or 480 for Phones, 1024 or 768 for Tablets.
h integer yes Height of the video player in device independent pixels (DIPS). Interstitial sizes include 320 or 480 for Phones, 1024 or 768 for Tablets.
placement integer yes Placement type for the impression. Refer to List 5.9 on IAB OpenRTB 2.5 specs for more details. The default value is 5.
linearity integer yes Indicates 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.
skip integer yes Indicates if the player will allow the video to be skipped, where 0=no, 1=yes.
delivery integer array yes Supported 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.
pos integer yes Ad position on screen. Refer to List 5.4 on IAB OpenRTB 2.5 specs for more details. The default value is 7.
companiontype integer array yes Supported VAST companion ad types. Refer to List 5.14 on IAB OpenRTB 2.5 specs for more details. The default value is 1, 2.
ext object yes Placeholder for custom extensions to OpenRTB.

Object: App 🔗

Attribute Type Always Passed? Description
id string yes Each demand partner specific publisher app ID
name string yes App name
bundle string yes App bundle ID
storeurl string yes App store URL for the publisher app
cat string array yes Array 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 Chartboost Mediation.
publisher object yes Details about the Publisher (Section 4.6) of the app.

Object: Publisher 🔗

Attribute Type Always Passed? Description
id string yes Demand partner specific publisher ID
name string yes Publisher name

Object: Device 🔗

Attribute Type Always Passed? Description
ua string no Browser 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)
geo object no Geo object (See: Object Geo) containing country, type, region, city, zip
lmt integer no “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0=tracking is unrestricted, 1=tracking must be limited per commercial guidelines
ip string no IPv4 address closest to device
devicetype integer no The general type of device. Refer to List 5.21 on IAB OpenRTB 2.5 specs for more details
make string no Device make (e.g., “Apple”)
model string no Device model (e.g., “iPhone”)
os string yes Device operating system (e.g., “iOS”)
osv string yes Device operating system version (e.g., “3.1.2”)
h integer yes Physical height of the screen in pixels
w integer yes Physical width of the screen in pixels
pxratio float no The ratio of physical pixels to device independent pixels
language string no Browser language using ISO-639-1-alpha-2
carrier string no Carrier or ISP (e.g., “VERIZON”)
connectiontype integer no Network connection type. Refer to List 5.22 on IAB OpenRTB 2.5 specs for more details
ifa string no ID sanctioned for advertiser use in the clear (i.e., not hashed)
ext.ifv string no ID sanctioned for vendor use. Includes iOS IDFV and Android App Set ID. This ID only be used for frequency capping purposes

Object: Geo 🔗

Attribute Type Always Passed? Description
type integer yes Source of location data. Refer to List 5.20 on IAB OpenRTB 2.5 specs for more details. The default value is 2 for Chartboost Mediation.
country string yes Country code using ISO-3166-1-alpha-3
region string yes Region code using ISO-3166-2; 2-letter state code if USA
city string yes City using United Nations Code for Trade & Transport Locations
zip string yes Zip or postal code

Object: User 🔗

Attribute Type Always Passed? Description
id string yes A unique identifier for the user on Chartboost Mediation
geo object yes Geo object (See: Object Geo) containing country, type, region, city, zip
ext.consent string yes Consent string for GDPR

Object: Regs 🔗

Attribute Type Always Passed? Description
coppa integer yes Require Coppa Compliant Ad. (0=No, 1=Yes) Will be omitted if No.
us_privacy string yes CCPA related regulation information. See IAB’s USPrivacy page for supported string formats.
ext.gdpr integer yes Subject to GDPR Regulations (0=No, 1=Yes)

Bid Request Sample 🔗

Note: below is just a sample bid request. The Chartboost 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"
  ]
}

Bid Response Sample 🔗

Note: below is just a sample bid response. The Chartboost 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}"
            ],
          }
        }
      ]
    }
  ]
}