API v2.0 to v3.0 migration
Improvements
- Support for Cross Ad Formats (video and banner) via one API.
- Support for Adchoices
- Support for multiple impression trackers and click trackers
- Client side impression and click confirmation enabling access to more extensive demand
- Improved user and display confirmation granting access to more CPM and CPC demand partners
Changes
- Change in Base URL (http: //api.pubnative.net/api/v3/native?{params})
- The following list of parameter names has been changed:
| API v2 | API v3 |
|---|---|
| app_token | apptoken |
| os_version | osver |
| ad_count | adcount |
| zone_id | zoneid |
| bundle_id | bundleid |
| device_model | devicemodel |
| click_url | link |
Note: Publisher should confirm all impression and click beacons client side.
Impression and click beacons MUST be confirmed on the client side
PubNative provides a complex mix of demand sources from premium advertisers to performance marketing partners and OpenRTB exchanges. Programmatic buyers are paying only when their impressions and clicks are confirmed in real-time. That is why it is essential to confirm the impression and click beacons in real time.
Please be noted that as soon as an impression (=creative) is shown to the user (and ONLY after the ad has been viewed for 1 second) the impression should be confirmed. This is the guideline is in order to respect IAB view-ability terms.
How are impression and click beacons confirmed?
- In case the beacon is of type url, then you must send us a GET request to the URL which is specified in impression beacon client side.
- In case the beacon is of type js, then you must render js script in a web view and confirm the impression on client side.
Note: Number of impression and click beacons depends on the demand partner. The integration must be done in such a way that the app is in a position to confirm all beacons -impression and click.
New Parameter Developments
- New param 'al' (ad layout) has been introduced. For more information please refer to ad layout section
- New param 'mf'(meta details). These parameters should be used to request for specific asset and meta information. Please refer to API v3.0 section for more details
- New parameter dnt, which specifies if user needs to tracked is mandatory
- 'idfa' or 'gid' are mandatory when 'dnt' is set
- Passing 'zoneid' is mandatory
- Support for different asset types, see Asset Types
- Major structural changes in the response. Please refer to API v3.0 section for more details. You can find a sample response below:
{
"status": "ok",
"ads": [
{
"link": "http://tr.pubnative.net/click/native?aid=4&t=-iTOxA6LFOzLGh_DqSPbyuah7H0rEM7zcJaLQXm9hkhi9NAiYyZf8N2OiuiAsVsfBij2ZsMcAh97C5gqqk8GVwYXy5mkWE7-EXWGeSstTM_WoEMWzfWCzGiPmQEcFelUKsC5KPAckKyHAub_-wBAWGxy-Sna6IsDOyfG0KA4Wf0VY6bfEIPK99zJD5SO6XCb4wN1J38jq0Eu3txiQoQ4rlhjB9Qy_1evMB8AtuVY4-Wzk6BW9oEbq0C3h3PSc_4sl_WBxqa_c2c1pGUvwZI2HiMsCPktuKkaxhOe2NAXFxjqmZLkFp8x72Jp-CfVpPrLGN4xgqaKHS19k39xiO7gGewgrmQ4-CzfsAxwkL1cTg-GlcxP_T754JsHs8dT2kePLXQDAkC4Kescw0VNOD28qvB_xYYx013EA9UZNgzgf06Lf-lEGXwYHNtT6_48bUYybeaCRhc77ToEIdBh3rIcEqikSTJoPNXLNyW3STPOvo16YjuAzDRk51fZSKUJ2X2CEwwRT6qrMCsU4sF3GQN_Rbau-bhLVcN78GTRhky84eJDauJ7IhplBtwwjAzY2zf-XL8QMOYgNNaR0nzHGiu2J52BFrfwB6J-nD6Befym1oh_4N50IepI5NbBDOaBHAhfR2hFUUPCygSujd9ubOfCJXYkdCXQb5BZcrDky-bDL_6emvlIGrwqgxr14Z_6rHiSSuQBUM_mk-PuhshDxtyfdkm_JjqpZaZHW8q9ALgcuQoHfZn8c9c0809WJHoripu7hnUNxKJDYKdD5zm61j7CvEKi2YrpkmcZMSvzaGlOKLv3Nzn5HKu59nF59cPp0wPajg",
"assetgroupid": 1,
"assets": [
{
"type": "icon",
"data": {
"w": 80,
"h": 80,
"url": "http://cdn.pubnative.net/games/icons/001/006/263/dimension_80x80.jpg?20160802094138"
}
},
{
"type": "title",
"data": {
"text": "Mobile Strike"
}
},
{
"type": "rating",
"data": {
"number": 4
}
},
{
"type": "cta",
"data": {
"text": "Installieren"
}
}
],
"meta": [],
"beacons": [
{
"type": "impression",
"data": {
"url": "http://tr.pubnative.net/impression?aid=4&t=m1sAZlOpZDA7BF6P5bU2vCv82IRUHwjew6Y-iqZ9NVu8JfVMJPwi3EYqaB4w9mj4oDZH5upSsn7c-0Y3p5qP12izP0TxgaT5iUw9wjH_1ndEWd2PrGa5hzVnri99wfMHYVVhU-E4ebfNJ3OV3Gmm--6HSd1ufIWRVEgngpJKojlLHmP-Yf6DqTFW7OIrhbXzs6tfV8CL0aAdMiLk3JQB4_41rm-8j79J8pbcu-vFuiEW4HZB5vkyIRsq4hwKZJDJeG-1z84-x-hkRmJ6UUFdcMUeDWPOCgbz1dgQ7IoqYeEhBI9_TyBtnZ39jqNrfiEV1-qpV5PiIKrpyyIUdCTn2y2TPkXQYez5mGCX0kMp67PgzG4FaLMSM6P-lsH2bCqqbBkW6cpPV-vnKd5rZ5WrHjs_Y4zDt3ptoZHetd92g2xTL7ez&tl=432"
}
}
]
}
]
}
{
"status": "ok",
"ads": [
{
"click_url": "https://tr.pubnative.net/click/native?aid=4&t=nebwjoul-I70w-V0mv4JQmV9l_0Y7AfxN7ByHNiL-qLlM41Eiw7z2tJzhdPN9NQ3WbhlI_JgcGSZSLAQrrOhqLIRTxZK-oFpzJzqdkBQvQatkvlMrNM5oc8_-CinAsAr8rrlArwL72pD1kpsPPdRHg0qEctvHkwfaRNkvTea1vfX-oM4sXzKY65GqHcVtsFF7eznYLJTaYUx7yZb1TmBC-gK8qfEKolzg7WnDlfEWwVVZUnn8M8gFVUF8U6XsafG6fqwGmOLsqmZ0UEnXrlqc1jZ65wKUVzo6JSSd6fYlAwcLxLWQXzrvLSHYpwLtpNczceJbyTr78can6a4g_Y0wHNrRIwzEPsAfY_ugBRmgd8k7uBn1FphSd3Ml8MLfQsgFtAQ12fbG9UvomuPreB2B7spOlT-NMZ9FhGLfA3a9Ro0zuGOvpU03E1tVpERVzX4S1fZanefVlNoW1jrUCy4ooG0lhT3u69oVw37lF5t-TsVRHq8mV2jskRTeH7mpifmc0O7PyRG0FBCcyhgktvBEn4ggwGxXFFMlg4rGvZQThzNJ1CHP13UcThmQ1M1K2MeCBpXI5TnfJXt15pjIhRvslHx2mERWr_QcTCiYzK_EOFTxp8fFZvuJBSwrqVOqTgIjBQau-y20RFs5D1u8kQg92RxYS-MN6ZIVpdDrGfQUS5HL__znXcvKCV-aadds6w1fklOq3gwMvJmwASWgk77JVrcHT2Ql3CvmccWhHomoRAXuBpAQqIWnhrz0ncU-U9e3P2tF61yKvKFBfK860Ak8G9jP8q7Pb1rPZxeasNrGhsd756MueCA5lTthWhCgL1VJRHN2HH7iK0F8tX9sYG9qW7p",
"points": 6180,
"revenue_model": "cpa",
"cta_text": "Installieren",
"type": "native",
"title": "Mobile Strike",
"description": "Zeit für eine neue App? Installiere mich jetzt.",
"banner_url": "https://cdn.pubnative.net/games/promo_images_landscape/001/006/263/dimension_1200x627.jpg?20151216055440",
"portrait_banner_url": "https://cdn.pubnative.net/games/promo_images_portrait/001/006/263/dimension_640x960.jpg?20151216055436",
"icon_url": "https://cdn.pubnative.net/games/icons/001/006/263/dimension_150x150.jpg?20160524072813",
"app_details": {
"name": "Mobile Strike",
"publisher": "Epic War",
"developer": "Epic War",
"store_rating": 4,
"category": "Games - Real Time Strategy",
"platform": "Android",
"review": "",
"review_url": null,
"review_pros": [],
"review_cons": [],
"version": null,
"size": "N/A",
"age_rating": "Everyone 10+Violent ReferencesLearn more",
"store_description": "",
"store_url": null,
"release_date": "2016-03-22",
"total_ratings": 355123,
"installs": "10,000,000 - 50,000,000",
"store_categories": [
"Strategy"
],
"sub_category": null,
"store_id": "com.epicwaronline.ms",
"url_scheme": null
},
"beacons": [
{
"type": "impression",
"url": "https://t.pubnative.net/tracking/imp?aid=4&t=idFutUmKZRL_lJ6W1qIKUgTwvlz_G2dycEbBRGDMfwOpe0Xs3ldHI1v2fpk5JdWJ65bifryNgaA7XYspZCxNruS9Oj1_IIEEoFIfRd6HIKxl_0Ggd487YdjhRMENP1KmZ1hdHXApYdSU0Qh5tDBjfpw3VrDzDK1RiKWObolZA7Kl0oSrG32CwzO4qdqjNBW9Gq2jNC7m78TZBtSPCY6tVKRPQlzGVABWiRF2yCv6pTXMc-n26htRHciLt60cnRtAxFl4Cgx0S9q_8IUyONeZn3wQB2KZc7qPiuVwjKmljKvSlOLkJWS7GKQh-fB3MX8hyGVV-MpIXwgbIyjOIsXCLIOe79OkcpP_9k-EJfMRWiv97d3hopB42ERONhfIq4LsFmVm323BPNWs9zo6M_uDRIeLJoGcTJ5njT3W06A3tb7ovzrtrg"
}
],
"cid": "3551019"
}
]
}