# Mediation OpenRTB Integration Chartboost Mediation (formerly Helium) uses the [OpenRTB V 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf){:target="_blank"} 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](#object-imp)) | | app | object | yes | Details via an App object (See: [Object App](#object-app)) about the publisher’s app. | | device | object | yes | Details via a Device object (See: [Object Device](#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](#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](#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](#object-banner)), this impression is offered as a banner ad opportunity.| |video|object|yes|A Video object (See: [Object Video](#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](#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](#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](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/US%20Privacy%20String.md){:target="_blank"} 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. ```json { "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. ```json { "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": "
<\/a><\/div>", "ext": { "imptrackers": [ "https:\/\/lb-www2.foobar.com\/ads\/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}" ], } } ] } ] } ```