API OF INTEGRATION
introduction of document
this document shows how developer(SSP, supply-side platform) integrate with Macan-native Adx.
Preparation before integration
You can get the Token in the account manager
steps of request/response
There are three steps in RTB processing:
User visits the site or APP that developer owns or serve for and make a ad request
Developer send the request to Macan-native Adx
Macan-native Adx reply developer Response
developer renders the ads according specification of this document
instruction
URL of request
When there is need to request ad, send a HTTP POST to the following address:
adx.macan-native.com/adx/{ssp_token}
Communication Mode and Encoding
The underlying communication protocol between Macan-native Ads ADX and SSP is HTTP, POST method, data using JSON format, UTF-8 encoding.
request
The Ad Request is a request sent by the SSP to the Macan-native Ads ADX to call for an ad, via the Request URL noted above.
Request field
| Attribute | Always Passed | description | |
|---|---|---|---|
| id | yes | Unique ID of the bid request, provided by the exchange. | |
| imp | yes | Array of Imp objects representing the impressions offered. At least 1 Imp object is required. | |
| app | yes | Details via an App object about the publisher’s app. | |
| device | yes | Details via a Device object about the user’s device to which the impression will be delivered. | |
| user | no | Details via a User object about the human user of the device. | |
| at | yes | Auction type.1 = First Price,2 = Second Price | |
| tmax | yes | Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange. | |
| cur | yes | Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. | |
| bcat | yes | Blocked advertiser categories using the IAB content categories. | |
| badv | yes | Blocked list of advertisers by their domains. | |
| bcat | yes | Blocked advertiser categories using the IAB content categories. | |
| bapp | yes | Block list of applications by their platform-specific exchange independent application identifiers. On Android, these should be bundle or package names. On iOS, these are numeric ids. | |
| source | yes | A Source object that provides data about the inventory source and which entity makes the final decision. | |
| regs | yes | A Regs object that specifies any industry, legal, or governmental regulations in force for this request. |
Imp information
| Attribute | Always Passed | description |
|---|---|---|
| id | yes | A unique identifier for this impression within the context of the bid request. |
| metric | no | An array of metrics. These metrics can offer insight into the impression to assist with decisioning such as average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value. |
| banner | no | A Banner object is required if this impression is offered as a banner ad opportunity. |
| video | mo | A Video object is required if this impression is offered as a video ad opportunity. |
| pmp | no | A PMP object containing any private marketplace deals in effect for this impression. |
| displaymanager | yes | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). |
| displaymanagerver | yes | Version of ad mediation partner, SDK technology, or player responsible for rendering ad. |
| id | yes | A unique identifier for this impression within the context of the bid request. |
| instl | yes | Value indicating whether the ad is an insterstitial. |
| bidfloor | yes | The minimum bid for this impression is expressed in CPM. |
| bidfloorcur | yes | Currency specified using ISO-4217 alpha codes. |
| clickbrowser | yes | Indicates the type of browser opened upon clicking the creative in an app. 0 = embedded 1 = native |
| secure | yes | Flag to indicate whether the impression requires secure HTTPS URL, creative assets, and markup.0 = non-secure 1 = secure If omitted, the secure state is unknown, and you should assume non-secure HTTP support. |
| exp | yes | Number of seconds that may elapse between the auction and the actual impression. Macan-native uses the following default cache times. |
| ext.brsrclk | yes | A custom extension used to force open the device's browser. When the bid request supports opening the device's external browser |
| ext.dpl | no | A custom extension that indicates the deep linking capability. |
| rwdd | yes | CIndicates whether the user receives a reward for viewing the ad. |
Banner information
| Attribute | Always Passed | description |
|---|---|---|
| format | No | Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended. |
| w | Yes | Exact wiMacan-nativeh in device independent pixels (DIPS); recommended if no format objects are specified. |
| h | Yes | Exact height in device independent pixels (DIPS); recommended if no format objects are specified. |
| btype | Yes | Blocked banner ad types. |
| battr | Yes | Blocked creative attributes. |
| pos | Yes | Ad position on the screen. |
| topframe | Yes | Indicates if the banner is in the top frame instead of an iframe.0 = no,1 = yes |
| mimes | Yes | Content MIME types supported. |
| expdir | No | Directions in which the banner may expand. |
| api | Yes | List of supported API frameworks for this impression. |
| id | Yes | Unique identifier for this banner object. |
| vcm | No | Relevant only for Banner objects used with a Video object in an array of companion ads. Indicates the companion banner rendering mode relative to the associated video.0 = concurrent,1 = end-card |
| ext.rewarded | Yes | Indicates whether rewarded playables are supported. 0 = Rewarded Playables are not supported,1 = Rewarded Playables are supported |
Video information
| Attribute | Always Passed | description |
|---|---|---|
| mimes | Yes | Content MIME types supported. |
| minduration | Yes | Minimum video ad duration in seconds. |
| maxduration | Yes | Maximum video ad duration in seconds. |
| protocols | Yes | Array of supported video protocols. Macan-native always passes 2, 5, 3, 6, 7, 8. |
| w | Yes | WiMacan-nativeh of the video player in pixels. |
| h | Yes | Height of the video player in pixels. |
| startdelay | Yes | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Macan-native always passes 0 for pre-roll. |
| placement | Yes | Placement type for the impression. Macan-native always passes 5 for interstitial video. |
| plcmt | No | Placement (video) type for the impression. Macan-native always passes 3 for interstitial placement type. |
| linearity | No | Indicates if the impression must be linear, nonlinear, etc. Macan-native always passes 1 for linear video. |
| skip | Yes | Indicates whether the player allows the video to be skipped.0 = no,1 = yes |
| skipmin | No | Videos of total duration greater than this number of seconds can be skippable. Only applicable if the ad is skippable. |
| skipafter | No | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. |
| battr | Yes | Blocked creative attributes. |
| maxbitrate | No | Maximum bit rate in Kbps. |
| playbackmethod | Yes | Playback methods that may be in use. Macan-native always respects the user's device settings. Macan-native always passes 5 for fullscreen video. |
| playbackend | Yes | The event that causes playback to end. Macan-native always passes 1. |
| pos | Yes | Ad position on screen. Macan-native always passes 7 for fullscreen. |
| companionad | Yes | An array of Banner objects if companion ads are available. |
| api | Yes | List of supported API frameworks for this impression. |
| companiontype | Yes | Supported VAST companion ad types. Macan-native always supports 1 (static), 2 (HTML), and 3 (iframe) when companionad is supported. |
| ext.rewarded | Yes | Macan-native always passes this custom extension for video requests.0 = Non-rewarded,1 = Rewarded |
| ext.mraidendcard | Yes | Macan-native always passes this custom extension for video requests.0 = MRAID end card is not supported,1 = MRAID end card is supported |
| ext.autostore | Yes | Indicates whether the inventory is eligible for Auto Store.0 = false,1 = true (default) |
| ext.dualendcard | No | Indicates whether the inventory is eligible for Dual End Card.0 = false,1 = true |
App information
| Attribute | Always Passed | description |
|---|---|---|
| id | yes | Application ID, generated by Macan-native Adx, such as "z0000001" or "iq3nktkh" |
| name | yes | app name |
| bundle | no | A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name, e.g., com.foo.mygame. On iOS, this is typically a numeric ID or app store ID. |
| domain | no | Domain of the app. |
| storeurl | no | App Store URL for an installed app. |
| cat | yes | Array of IAB content categories of the app. |
| ver | yes | application version |
| privacypolicy | yes | Indicates if the app has a privacy policy.0 = no 1=yes |
| paid | no | Indicates whether app is the free or paid version.0 = app is free version 1 = app is a paid version |
| publisher | yes | Details about the Publisher of the app. ext.devuserid No A developer's own persistent unique user identifier. |
| ext.storecat | No | Google Play and Apple App Store category definitions. For example, Games. |
| ext.storesubcat | No | Google Play and Apple App Store Sub-game category definitions. The array is always capped at 3 strings. |
| ext.fmwname | No | A string value describing if the app is using the unity or native framework, listed as unity or native. |
| ext.apilevel | No | (Android only) An integer value that specifies the API level supported. |
Publisher information
| Attribute | Always Passed | description |
|---|---|---|
| id | yes | Exchange-specific publisher id. |
| name | yes | Publisher name (may be aliased at the publisher’s request). |
| domain | no | Highest level domain of the publisher. |
Device information
| Attribute | Always Passed | description |
|---|---|---|
| ua | Yes | Browser user agent string that informs about device data. |
| dnt | Yes | Standard “Do Not Track” flag as set in the header by the browser.0 = tracking is unrestricted,1 = do not track |
| lmt | No | Commercially endorsed Limit Ad Tracking signal (e.g., iOS, Android). 0 = tracking is unrestricted,1 = tracking must be limited per commercial guidelines |
| ip | Yes | IPv4 address closest to device. Example, 86.179.150.0 |
| ipv6 | No | IP address closest to device as IPv6. |
| devicetype | Yes | The general type of device. |
| make | No | Device make. |
| model | No | Device model. |
| os | No | Device operating system. |
| osv | No | Device operating system version. |
| hwv | No | Hardware version of the device. |
| h | Yes | Physical height of the screen in pixels. |
| w | Yes | Physical wiMacan-nativeh of the screen in pixels. |
| ppi | No | Screen size as pixels per linear inch. |
| pxratio | No | The ratio of physical pixels to device-independent pixels. |
| js | Yes | Support for JavaScript. 0 = no,1 = yes |
| language | Yes | Browser language using ISO-639-1-alpha-2. |
| carrier | No | Carrier or ISP using exchange curated string names which should be published to bidders a priority. |
| connectiontype | Yes | Network connection. |
| ifa | Yes | Clear (not hashed) device identifier. |
| ext.inputLanguage | No | A string array containing the languages setup on the user's device keyboard. |
| ext.ifv | No | (iOS only). A persistent unique identifier for each app on a device that identifies the device to the app's vendor. The value of this property is the same for apps that come from the same vendor running on the same device. A different value is returned for apps on the same device that come from different vendors, and for apps on different devices regardless of vendor. |
| ext.atts | No | (iOS only) An integer passed to represent the app's app. tracking authorisation status.0 = not determined,1 = restricted,2 = denied,3 = authorized |
| ext.inputlanguage | No | A string array containing the languages setup on the user's device keyboard. Country codes are passed in the string array. |
| ext.diskspace | No | An integer value describing the available disk space on the device in megabytes, where "18201" = device has 18201 MB of available disk space. MB will be rounded up and passed as a whole number to align with Apple's data user and user privacy. |
| ext.totaldisk | No | An integer value describing the total disk space on the device in megabytes, where "63989" = 63989 MB of total disk space. MB will be rounded up and passed as a whole number to align with Apple's data use and user privacy. |
| ext.ringmute | No | (Android only) An integer value describing the device sound setting during time of ad request describing if sound is set to ring or mute.0 = ring,1 = mute |
| ext.charging | No | An integer value describing if the device is connected to a charger.0 = unplugged,1 = plugged into power outlet |
| ext.bluetooth | No | A boolean value indicating if the device is connected to bluetooth.0 = not connected via bluetooth,1 = connected via bluetooth |
| ext.headset | Yes | A boolean value indicating if the device is connected to a wired headset.0 = no wired headset is connected,1 = device is connected to any wired headset |
| ext.batterylevel | No | An integer passed describing percentage of battery charge remaining on the user's device, segmented into buckets.1 = less than 5%,2 = 9-5%,3 = 21-10%,4 = 39-25%,5 = 54-40%,6 = 69-55%,7 = 84-70%,8 = 100-85% |
| ext.batterysaver | No | A boolean value indicating if battery saver (Low Power Mode on iOS) has been enabled.0 = battery saver not enabled,1 = battery saver enabled |
| ext.darkmode | No | A boolean value indicating if dark mode is enabled on the device.0 = dark mode not enabled,1 = dark mode enabled |
| ext.airplane | No | (Android only) A boolean value indicating if airplane mode is enabled.0 = airplane mode not enabled,1 = airplane mode enabled |
| ext.dnd | No | (Android only) A boolean value indicating if do not disturb setting is enabled.0 = do not disturb not enabled,1 = do not disturb enabled |
Geo information
| Attribute | Always Passed | description |
|---|---|---|
| lat | No | Latitude from –90.0° to +90.0°, where negative is south. |
| lon | No | Longitude from –180.0° to +180.0°, where negative is west. |
| type | No | Source of location data; recommended when passing lat/lon. |
| accuracy | No | Estimated location accuracy in meters; recommended when lat/lon are specified and derived from the location service on a device. |
| lastfix | No | The number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken. |
| ipservice | No | Service or provider used to determine geolocation from IP address if applicable. |
| country | Yes | Country code using ISO-3166-1-alpha-3. |
| region | No | Region code using ISO-3166-2; 2-letter state code if USA. |
| city | No | City using United Nations Code for Trade & Transport Locations. For more information about UN codes, see Appendix A of the OpenRTB Specification version 2.5. |
| zip | No | The home zip or postal code of the user. |
| utcoffset | No | Local time as the number +/– of minutes from UTC. |
| dma | Yes | Maxmind DMA code based on IP. |
| metro | Yes | Maxmind Metro code based on IP. |
User information
| Attribute | Always Passed | description |
|---|---|---|
| yob | No | Year of birth as a 4-digit integer. |
| gender | No | Gender.M = male,F = female,O = known to be other, i.e., omitted is unknown |
| ext.consent | Yes | Extension to signal whether or not the user subject to GDPR regulations has given consent. |
| ext.impdepth | No | The count of impressions for a specific placement type in a given app session. The impression depth is reset once the session ends. |
| ext.sessionduration | No | The total duration of a time a user has spent so far in a specific app session expressed in seconds. For example, a user has been playing Word Game for 45 seconds. |
| ext.lastbundle | No | (iOS only) The last app bundle the user saw on the previous impression in a given session per placement type. |
| ext.lastadomain | No | The last advertiser domain the user saw on the previous impression in a given session per placement type. |
| ext.clickrate | No | The percentage of clicks or impressions per user per placement type over a given number of impressions. For example, 5 represents a 5% CTR. |
| ext.lastclick | No | VAST specific. A boolean value indicating if the user skipped the video on the last impression in a given session, where 1 = user skipped |
| ext.lastclicktype | No | VAST Specific. An integer value indicating what part of the video the user clicked on.0 = no click,1 = ClickThrough,2 = CompanionClickThrough |
| ext.completionrate | No | For Rewarded and Video placement types, the percentage of completions or impressions per user per placement type for a given number of impressions. For example, 70 indicates a 70% completion rate. |
Bid Response Specifications
When replying to a bid request for a Rewarded Playable ad, you must include specific values in your bid response. For more information about what to include in your response.
BidResponse
| Attribute | Always Passed | description |
|---|---|---|
| id | Yes | The bid response id must be the same as the bid request ID. They are used for tracking purposes. |
| seatbid | Yes | Array of seatbid objects. A bid must contain one or more seatbid objects. |
| bid | No | Bidder generated response ID for logging and tracking purposes. |
| cur | No | Bid currency using ISO-4217 alpha codes. USD is the only supported currency on Macan-native |
SeatBid
| Attribute | Always Passed | description |
|---|---|---|
| bid | Yes | Array of one or more Bid objects each related to an impression. Multiple bids can relate to the same impression. |
| seat | Yes | ID of the buyer seat, e.g., advertiser, agency, etc. on whose behalf this bid is made. |
Bid
| Attribute | Always Passed | description |
|---|---|---|
| id | Yes | Bidder generated bid ID for logging/tracking purposes. |
| impid | Yes | ID of the Imp object in the related bid request. |
| price | Yes | Bid price expressed as CPM although the actual transaction is for a unit impression only. |
| nurl | No | Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup. Substitution macros (Section 4.4) may be included in both the URL and optionally returned markup. |
| burl | Yes | Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). May include substitution macros (Section 4.4). |
| lurl | No | Loss notice URL called by the exchange when a bid is known to have been lost. May include substitution macros (Section 4.4). Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed, i.e., replaced with a zero-length string. |
| adm | Yes | Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. May include substitution macros (Section 4.4). |
| adomain | Yes | Advertiser domain for block list checking, e.g., “xyzco.com”. This can be an array in the case of rotating creatives. Exchanges can mandate that only one domain is allowed. |
| bundle | No | A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this is the bundle or package name, e.g., com.foo.mygame. On iOS, it is a numeric ID. |
| iurl | No | URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. |
| cid | Yes | Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. |
| crid | Yes | Creative ID to assist with ad quality checking. |
| cat | No | IAB content categories of the creative. Refer to List 5.1 of the OpenRTB Specification version 2.5. |
| attr | No | Set of attributes describing the creative. |
| dealid | No | If this bid pertains to a private marketplace direct deal, this is a reference to the deal.id from the bid request. |
| ext.crtype | No | Custom extension used to identify the type of ad markup with which the DSP responds. |
| ext.skadn | No | Extension to submit the click data and signature to SKAdNetwork for attribution. |
| ext.autostore | No | |
| Indicates whether Macan-native should enable automatically displaying the Store.0 = false,1 = true,For more information about displaying the Store, see Auto Store. | ||
| ext.autostoreclick | No | Indicates whether Macan-native Exchange should fire click trackers when displaying the Store.0 = false,1 = true; For more information about options when displaying the Store, see Auto Store. |
| ext.dualendcard | No | Indicates whether Macan-native should render the Dual End Card.0 = false,1 = true |