{"_id":"57838c987c7a850e00faa52d","project":"574ff4bd3fa1870e00889ba6","parentDoc":null,"editedParams":true,"version":{"_id":"574ff4bd3fa1870e00889ba9","project":"574ff4bd3fa1870e00889ba6","__v":20,"createdAt":"2016-06-02T08:56:29.492Z","releaseDate":"2016-06-02T08:56:29.492Z","categories":["574ff4bd3fa1870e00889baa","577278ecdceb570e003a9001","577279865617b117009e643f","577279985617b117009e6440","577279bc8c48e00e00503504","5774fe18605b770e0037be8a","577ce3ad87acf617003c4187","577f8476a77c700e006a6c52","57b486ae0d2b640e00e9d3f5","57b722133d3e620e004ec74b","57bd95f00fe3a00e003e2cc5","57c8349359cd4b0e00b888ef","57c8349b5754fa1700b12242","57cedb0bad483e0e00890239","57cedbe807d7ea0e00e438cc","57d82967156ef72b007ffcd8","58ee353ad1ee2f0f0034a13d","596623221738df00298622a5","59a51730192dba000fc9ca38","59a8129f1e7b26000fa0fb1a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"__v":2,"user":"5770dd042659e20e00c90a98","category":{"_id":"5774fe18605b770e0037be8a","__v":0,"project":"574ff4bd3fa1870e00889ba6","version":"574ff4bd3fa1870e00889ba9","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-06-30T11:10:16.206Z","from_sync":false,"order":1,"slug":"api-documentation","title":"API Documentation"},"editedParams2":true,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-11T12:10:00.215Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"GET /partner/v2/promotions/nativeapp_token=YOURAPPTOKEN&bundle_id=422689480&icon_size=80x80&banner_size=1200x627&ip=172.16.254.1&os=ios&os_version=9.1&device_model=iphone6s&server_integration=1&apple_idfa=771468523E3346ABAA04E207BBAF094B&user_agent=Mozilla%2F5.0%20%28iPod%20touch%3B%20CPU%20iPhone%20OS%207_1_2%20like%20Mac%20OS%20X%29%20AppleWebKit%2F537.51.2%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F11D257HTTP/1.1\nHost: api.pubnative.net","language":"curl"}]},"method":"get","results":{"codes":[{"code":"{\n  \"status\": \"ok\",\n  \"ads\": [\n    {\n      \"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\",\n      \"points\": 6180,\n      \"revenue_model\": \"cpa\",\n      \"cta_text\": \"Installieren\",\n      \"type\": \"native\",\n      \"title\": \"Mobile Strike\",\n      \"description\": \"Zeit für eine neue App? Installiere mich jetzt.\",\n      \"banner_url\": \"https://cdn.pubnative.net/games/promo_images_landscape/001/006/263/dimension_1200x627.jpg?20151216055440\",\n      \"portrait_banner_url\": \"https://cdn.pubnative.net/games/promo_images_portrait/001/006/263/dimension_640x960.jpg?20151216055436\",\n      \"icon_url\": \"https://cdn.pubnative.net/games/icons/001/006/263/dimension_150x150.jpg?20160524072813\",\n      \"app_details\": {\n        \"name\": \"Mobile Strike\",\n        \"publisher\": \"Epic War\",\n        \"developer\": \"Epic War\",\n        \"store_rating\": 4,\n        \"category\": \"Games - Real Time Strategy\",\n        \"platform\": \"Android\",\n        \"review\": \"\",\n        \"review_url\": null,\n        \"review_pros\": [],\n        \"review_cons\": [],\n        \"version\": null,\n        \"size\": \"N/A\",\n        \"age_rating\": \"Everyone 10+Violent ReferencesLearn more\",\n        \"store_description\": \"\",\n        \"store_url\": null,\n        \"release_date\": \"2016-03-22\",\n        \"total_ratings\": 355123,\n        \"installs\": \"10,000,000 - 50,000,000\",\n        \"store_categories\": [\n          \"Strategy\"\n        ],\n        \"sub_category\": null,\n        \"store_id\": \"com.epicwaronline.ms\",\n        \"url_scheme\": null\n      },\n      \"beacons\": [\n        {\n          \"type\": \"impression\",\n          \"url\": \"https://t.pubnative.net/tracking/imp?aid=4&t=idFutUmKZRL_lJ6W1qIKUgTwvlz_G2dycEbBRGDMfwOpe0Xs3ldHI1v2fpk5JdWJ65bifryNgaA7XYspZCxNruS9Oj1_IIEEoFIfRd6HIKxl_0Ggd487YdjhRMENP1KmZ1hdHXApYdSU0Qh5tDBjfpw3VrDzDK1RiKWObolZA7Kl0oSrG32CwzO4qdqjNBW9Gq2jNC7m78TZBtSPCY6tVKRPQlzGVABWiRF2yCv6pTXMc-n26htRHciLt60cnRtAxFl4Cgx0S9q_8IUyONeZn3wQB2KZc7qPiuVwjKmljKvSlOLkJWS7GKQh-fB3MX8hyGVV-MpIXwgbIyjOIsXCLIOe79OkcpP_9k-EJfMRWiv97d3hopB42ERONhfIq4LsFmVm323BPNWs9zo6M_uDRIeLJoGcTJ5njT3W06A3tb7ovzrtrg\"\n        }\n      ],\n      \"cid\": \"3551019\"\n    }\n  ]\n}","name":"","status":200,"language":"json"},{"name":"No Fill","code":"{\n  \"ads\": [],\n  \"status\": \"ok\"\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"577a46d2aea88b0e00f63344","ref":"","in":"path","required":true,"desc":"This is your secure internal app token that you fetch from the publisher dashboard","default":"","type":"string","name":"app_token"},{"_id":"577a4a90aea88b0e00f63358","ref":"","in":"path","required":true,"desc":"The bundle identifier of the requesting app. i.e. com.my.app, 422689480","default":"","type":"string","name":"bundle_id"},{"_id":"577a4a90aea88b0e00f63356","ref":"","in":"path","required":true,"desc":"The size of icon ad being requested. Values will be in the format width x height, i.e. 80 x 80","default":"","type":"string","name":"icon_size"},{"_id":"577a4a90aea88b0e00f63355","ref":"","in":"path","required":true,"desc":"The size of banner ad being requested. Values will be in the format width x height, i.e. 1200x627","default":"","type":"string","name":"banner_size"},{"_id":"577a4a90aea88b0e00f63354","ref":"","in":"path","required":true,"desc":"The operating system of requesting device, i.e. ios, android","default":"","type":"string","name":"os"},{"_id":"577a4a90aea88b0e00f63353","ref":"","in":"path","required":true,"desc":"The model of the requesting device","default":"","type":"string","name":"device_model"},{"_id":"577a4a90aea88b0e00f63352","ref":"","in":"path","required":true,"desc":"The operating system version of the requesting device","default":"","type":"string","name":"os_version"},{"_id":"577a4a90aea88b0e00f63351","ref":"","in":"query","required":false,"desc":"Must be set to \"1\" if user identifier is not available; however, publishers are advised to use \"1\" ONLY when no user identifier is available, because using this parameter can result in a lower conversion rate.","default":"","type":"string","name":"no_user_id"},{"_id":"577a4a90aea88b0e00f63350","ref":"","in":"query","required":false,"desc":"The partner company name","default":"","type":"string","name":"partner"},{"_id":"577a4a90aea88b0e00f6334f","ref":"","in":"query","required":false,"desc":"The locale used. i.e. DE","default":"","type":"string","name":"locale"},{"_id":"577a4a90aea88b0e00f6334e","ref":"","in":"query","required":false,"desc":"This is the size of portrait banner image which needs to be returned. i.e. 320x480,  640x960 (default)","default":"640x960","type":"string","name":"portrait_banner_size"},{"_id":"577a4a90aea88b0e00f6334d","ref":"","in":"query","required":false,"desc":"The requesting device resolution. Values will be in format width x height","default":"","type":"string","name":"device_resolution"},{"_id":"577a4b5988c9800e0051909a","ref":"","in":"query","required":false,"desc":"The type of the device. Can be tablet for iOS or Android tablets or phone . For iPods, please use phone i.e. \"phone\", \"tablet\"","default":"","type":"string","name":"device_type"},{"_id":"577a4b5988c9800e00519099","ref":"","in":"query","required":false,"desc":"Number of Apps to return. Possible values: 1 (default) to 20","default":"1","type":"string","name":"ad_count"},{"_id":"577a4b5988c9800e00519098","ref":"","in":"query","required":false,"desc":"The ad zone identifier","default":"","type":"string","name":"zone_id"},{"_id":"577a4b5988c9800e00519097","ref":"","in":"query","required":false,"desc":"The current latitude of the requesting device","default":"","type":"string","name":"lat"},{"_id":"577a4b5988c9800e00519096","ref":"","in":"query","required":false,"desc":"The current longitude of the requesting device","default":"","type":"string","name":"long"},{"_id":"577a4b5988c9800e00519095","ref":"","in":"query","required":false,"desc":"The user's gender. i.e.  \"male\", \"female\", \"other\"","default":"","type":"string","name":"gender"},{"_id":"577a4b5988c9800e00519094","ref":"","in":"query","required":false,"desc":"The user's age","default":"","type":"string","name":"age"},{"_id":"577a4b5988c9800e00519093","ref":"","in":"query","required":false,"desc":"a comma separated list of keywords","default":"","type":"string","name":"keywords"},{"_id":"577a4a90aea88b0e00f63357","ref":"","in":"query","required":false,"desc":"A parameter that identifies the user's device (example: apple_idfa , android_advertiser_id) Programmatic buyers are frequently running retargeting campaigns or use negative targeting for improving the performance of their ads so it’s required to submit standard User Identifiers. (See full details below)","default":"","type":"string","name":"User Identifiers"},{"_id":"57c052376505682200277edb","ref":"","in":"path","required":false,"desc":"Must be set to \"1\"","default":"","type":"string","name":"server_integration"},{"_id":"57c052376505682200277eda","ref":"","in":"path","required":false,"desc":"The IP address of the device (user) received from the device request (IPv4 or IPv6)","default":"","type":"string","name":"ip"}],"url":"/partner/v2/promotions/native?app_token=:app_token&bundle_id=:bundle_id&icon_size=:icon_size&banner_size=:banner_size&os=:os&ip=:ip&server_integration=:server_integration&os_version=:os_version&device_model=:device_model&apple_idfa=:apple_idfa"},"isReference":true,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Endpoint\"\n}\n[/block]\n* Supported ad formats: native\n* Request method: GET\n* Response format: json\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to use?\"\n}\n[/block]\n* The server generates a GET request to the relevant ad-format together with the url param, the server returns a json response.\n* When the ad is shown, our server must be notified about the impression (See [About Confirming Impressions](http://developers.pubnative.net/v3.0/docs/server-to-server-api-v20-1#section-about-confirming-impressions) )\n* The server parses the json according to the adformat \n* When user clicks on the ad, the server should redirect to the URL which is specified in ad's click_url:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ads: [\\n{\\n\\tclick_url: \\\"https://t.pubnative.net/tracking/click?aid=1001000&t=...\\\"\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## User Identifiers\n\nPlease use one of the parameters below, **listed in a waterfall by the order of the rows**.\n[block:html]\n{\n  \"html\": \"<div>\\n<table>\\n  <tr>\\n    <th>Name</th>\\n    <th>Description</th>\\n    <th>Platform</th>\\n    <th>Example</th>\\n  </tr>\\n  <tr>\\n    <td>apple_idfa</td>\\n    <td>Apple ID for Advertising</td>\\n    <td>iOS 6+</td>\\n    <td>771468523E3346ABAA04E207BBAF094B</td>\\n  </tr>\\n  <tr>\\n    <td>apple_idfa_sha1</td>\\n    <td>Apple ID for Advertising (SHA1)</td>\\n    <td>iOS 6+</td>\\n    <td>ee5c19f8cf370b5978f4b9f33343a5e79c58df9a</td>\\n  </tr>\\n  <tr>\\n    <td>apple_idfa_md5</td>\\n    <td>Apple ID for Advertising (MD5)</td>\\n    <td>iOS 6+</td>\\n    <td>bb1e0285fbb97ba83fdb4e72514d62f5</td>\\n  </tr>\\n  <tr>\\n    <td>android_advertiser_id</td>\\n    <td>Android Advertiser Id</td>\\n    <td>Android 2.3+</td>\\n    <td>38400000-8cf0-11bd-b23e-10b96e40000d\\n    <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\\n  </tr>\\n  <tr>\\n    <td>android_advertiser_id_sha1</td>\\n    <td>Android Advertiser Id (SHA1)</td>\\n    <td>Android 2.3+</td>\\n    <td>4dfaa92388699ac6539885aef1719293879985bfp\\n    <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\\n  </tr>\\n  <tr>\\n    <td>android_advertiser_id_md5</td>\\n    <td>Android Advertiser Id (MD5)</td>\\n    <td>Android 2.3+</td>\\n    <td>4dfaa92388699ac6539885aef1719293879985bf\\n      <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\\n  </tr>\\n</table>\\n</div>\\n\\n<style></style>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"isa_info\\\">\\n  <strong><font color=\\\"7d0a80\\\">Please use raw versions!</font></strong>  In order to ensure the most accurate conversion tracking, please use the raw versions (other than the SHA1/MD5) if possible.\\n</div> \"\n}\n[/block]\n##About Confirming Impressions\nImpression beacons MUST be confirmed. PubNative provides a complex mix of demand sources from premium advertisers to performance marketing partners and OpenRTB exchanges. The programmatic buyers are paying only when their impressions are confirmed in real-time. That is why it is essential to confirm the impression beacons in real time. Please be noted as soon as an impression (=creative) is shown to the user and ONLY after the ad has been viewed for 1 second should the impression be confirmed. This is the guideline is in order to respect IAB viewability terms.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d3d1ccd-1.png\",\n        \"1.png\",\n        914,\n        181,\n        \"#bdbcbd\"\n      ]\n    }\n  ]\n}\n[/block]\n## Response Parameters\n[block:html]\n{\n  \"html\": \"<div>\\n<table>\\n  <tr>\\n    <th>Parameter</th>\\n    <th>Description</th>\\n    <th>Format</th>\\n    <th>RTB Compatable</th>\\n  </tr>\\n  <tr>\\n    <td>title</td>\\n    <td>App title</td>\\n    <td>string</td>\\n    <td>YES</td>\\n  </tr>\\n  <tr>\\n    <td>description</td>\\n    <td>App description</td>\\n    <td>string</td>\\n    <td>YES</td>\\n  </tr>\\n  <tr>\\n    <td>cta_text</td>\\n    <td>Call to action text</td>\\n    <td>string</td>\\n    <td>YES</td>\\n  </tr>\\n  <tr>\\n    <td>icon_url</td>\\n    <td>Icon CDN url</td>\\n    <td>url</td>\\n    <td>YES\\n    <p><i>only 80x80 - Please check if this size\\nfits with your tablets or other high resolution screens</p></i></td>\\n  </tr>\\n  <tr>\\n    <td>banner_url</td>\\n    <td>Banner CDN url</td>\\n    <td>url</td>\\n    <td>YES\\n    <p><i>only 1200x627</p></i></td>\\n  </tr>\\n  <tr>\\n    <td>click_url</td>\\n    <td>Click through url</td>\\n    <td>url</td>\\n    <td>YES</td>\\n  </tr>\\n  <tr>\\n    <td>beacons.type</td>\\n    <td> </td>\\n    <td> </td>\\n    <td>YES</td>\\n  </tr>\\n <tr>\\n    <td>beacons</td>\\n    <td> </td>\\n    <td> </td>\\n    <td>YES</td>\\n  </tr>\\n <tr>\\n    <td>revenue_model</td>\\n    <td>CPA <i>To collect this identifier, you need to include Google Play Services SDK in your app</i>\\n      <p>CPC<i> Cost Per Click</i></p>\\n      <p>CPM <i>Cost Per Mille, which is a cost for every 1,000 impressions</i></p></td>\\n    <td>string</td>\\n    <td>YES</td>\\n  </tr>\\n<tr>\\n    <td>points</td>\\n  <td>CPA campaign <i>1 point = 0.001 USD per 1 conversion</i>\\n    <p>CPM campaign <i>1 point = 0.001 USD per 1,000 impressions</i></p>\\n    <p>CPM <i>Cost Per Mille, which is a cost for every 1,000 impressions</i></p>\\n  \\t<p>CPC campaign <i>1 point = 0.001 USD per 1 click</i></p>\\n    <p>if the points value is 0, please notify the PubNative team</p>\\n  </td>\\n    <td>integer</td>\\n    <td>limited</td>\\n  </tr>\\n</table>\\n</div>\\n\\n<style></style>\"\n}\n[/block]\n## Frequently Asked Questions\n**1. What is impression confirmation?**\n    When the ad is shown, our server must be notified about the impression in order to track the campaign performance correctly.\n**2. When should be the impression be confirmed?**\nWhenever a user sees the ad for the first time for a minimum duration of 1 second, the impression beacon should be fired immediately, in real-time.\n**3. Why is impression confirmation required?**\nThe impression confirmation is a critical part of RTB compliance as well as for the eCPM maximization algorithm and the impression beacon should be triggered when the user actually sees the ad. One of the reasons for this is that campaigns available via RTB are CPM based and if we do not have the impression confirmation at 'seeing' stage, then the revenue will not be counted properly.\n**4. How is the impression confirmed?**\nYou must send us a GET request to the URL which is specified in impression beacon as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ads: [\\n\\tbeacons: [\\n\\t\\t{\\n\\t\\t\\ttype: \\\"impression\\\",\\n\\t\\t\\turl: \\\"https://t.pubnative.net/tracking/imp?aid=1001000&t=...\\\"\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"isa_info\\\">\\n  <strong><font color=\\\"7d0a80\\\">Use all available parameters:</font></strong>  Please be noted that overall performance depends on the number of submitted targeting criteria. For example, if you decide to share age, gender, location and other demographics in the request, it makes it easier to win impressions for RTB demands; thus, we highly recommend that you send us all the parameters you have available.\\n</div> \"\n}\n[/block]\n## Adding Postback\n\nIf you wish to receive conversion postback of certain parameter you send for example, Click ID, add \"&aff_sub={YourClickID}\" at the end of API click_url.  \n\nFor example: https ://t.pubnative.net/tracking/click?aid=1001000&t=...&aff_sub={YourClickID}\n[block:html]\n{\n  \"html\": \"<div class=\\\"isa_info\\\">\\n  <strong><font color=\\\"7d0a80\\\">Note!</font></strong>   Please send the PubNative team your postback URL with Click ID parameter.  After setting up our team will guide you through the test.\\n</div> \"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Checklist Before Activation\"\n}\n[/block]\nAfter the integration is complete, all that remains is to test the integration and make sure everything is working properly.\n\n## Request\n*Your request URL includes all required parameters with correct value\n*Your request URL includes user identifiers. (Android Advertiser ID or Apple IDFA\n*You are sending requests when user reaches the ad inventory and with planned frequency.\n*The best practice is to request a maximum of 3 ads per user session. Ads should be refreshed after an event (click or download) or after period of non-engagement. This period depends on the length of user sessions and can be from 1 minute to 3 minutes.\n\n## Response\nYour app works correctly even when there is no fill (API returns no ads). In case anything is wrong with the app PubNative can disable the fill and later enable it back on when the encountered problems are fixed.\n \n## Impression\n* You are confirming impressions when the user sees the ad for the first time for a minimum duration of 1 second\n* You are confirming impressions immediately, in real-time\n* You shouldn’t confirm impressions twice, even if the user sees the same ad again. One (initial) confirmation is enough\n\n## Clicks\n* Click happens when the user clicks the advertisement which is linked with the click URL PubNative provides\n* The click event has to be done by a genuine user and should not be an automated bot or incentivized (rewarded) click\n* Depending on the type of campaign (app promotion or mobile landing page) the redirect behaviour should be considered\n* For App promotion campaigns, background redirect (hidden browser/webview) is permitted in order to maintain the user experience\n* For mobile landing pages, at the end of the redirect you must make sure to either show an internal browser window (better user experience) or send the user directly to the default mobile browser \n\n**Please also send your request URL to PubNative team so we can help you to make sure everything is properly setup and ready to go live!**\n\n**If you have any questions, don’t hesitate to get in touch: support:::at:::pubnative.net**\n[block:html]\n{\n  \"html\": \"<div></div>\\n\\n<style>\\n.isa_info {\\nmargin: 10px 0px;\\npadding:12px;\\n}\\n\\n.isa_info {\\n    color: #424242;\\n    background-color: #dcdcdc;\\n}\\n\\n.isa_info i {\\n    margin:10px 22px;\\n    font-size:16px;\\n    vertical-align:middle;\\n}\\n</style>\"\n}\n[/block]","excerpt":"","slug":"server-to-server-api-v20-1","type":"endpoint","title":"Server-to-Server API v2.0 (Deprecated)"}

getServer-to-Server API v2.0 (Deprecated)


Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

app_token:
required
string
This is your secure internal app token that you fetch from the publisher dashboard
bundle_id:
required
string
The bundle identifier of the requesting app. i.e. com.my.app, 422689480
icon_size:
required
string
The size of icon ad being requested. Values will be in the format width x height, i.e. 80 x 80
banner_size:
required
string
The size of banner ad being requested. Values will be in the format width x height, i.e. 1200x627
os:
required
string
The operating system of requesting device, i.e. ios, android
device_model:
required
string
The model of the requesting device
os_version:
required
string
The operating system version of the requesting device
server_integration:
string
Must be set to "1"
ip:
string
The IP address of the device (user) received from the device request (IPv4 or IPv6)

Query Params

no_user_id:
string
Must be set to "1" if user identifier is not available; however, publishers are advised to use "1" ONLY when no user identifier is available, because using this parameter can result in a lower conversion rate.
partner:
string
The partner company name
locale:
string
The locale used. i.e. DE
portrait_banner_size:
string640x960
This is the size of portrait banner image which needs to be returned. i.e. 320x480, 640x960 (default)
device_resolution:
string
The requesting device resolution. Values will be in format width x height
device_type:
string
The type of the device. Can be tablet for iOS or Android tablets or phone . For iPods, please use phone i.e. "phone", "tablet"
ad_count:
string1
Number of Apps to return. Possible values: 1 (default) to 20
zone_id:
string
The ad zone identifier
lat:
string
The current latitude of the requesting device
long:
string
The current longitude of the requesting device
gender:
string
The user's gender. i.e. "male", "female", "other"
age:
string
The user's age
keywords:
string
a comma separated list of keywords
User:
string
A parameter that identifies the user's device (example: apple_idfa , android_advertiser_id) Programmatic buyers are frequently running retargeting campaigns or use negative targeting for improving the performance of their ads so it’s required to submit standard User Identifiers. (See full details below)

Examples


Result Format


Documentation

[block:api-header] { "type": "basic", "title": "Endpoint" } [/block] * Supported ad formats: native * Request method: GET * Response format: json [block:api-header] { "type": "basic", "title": "How to use?" } [/block] * The server generates a GET request to the relevant ad-format together with the url param, the server returns a json response. * When the ad is shown, our server must be notified about the impression (See [About Confirming Impressions](http://developers.pubnative.net/v3.0/docs/server-to-server-api-v20-1#section-about-confirming-impressions) ) * The server parses the json according to the adformat * When user clicks on the ad, the server should redirect to the URL which is specified in ad's click_url: [block:code] { "codes": [ { "code": "ads: [\n{\n\tclick_url: \"https://t.pubnative.net/tracking/click?aid=1001000&t=...\"\n", "language": "javascript" } ] } [/block] ## User Identifiers Please use one of the parameters below, **listed in a waterfall by the order of the rows**. [block:html] { "html": "<div>\n<table>\n <tr>\n <th>Name</th>\n <th>Description</th>\n <th>Platform</th>\n <th>Example</th>\n </tr>\n <tr>\n <td>apple_idfa</td>\n <td>Apple ID for Advertising</td>\n <td>iOS 6+</td>\n <td>771468523E3346ABAA04E207BBAF094B</td>\n </tr>\n <tr>\n <td>apple_idfa_sha1</td>\n <td>Apple ID for Advertising (SHA1)</td>\n <td>iOS 6+</td>\n <td>ee5c19f8cf370b5978f4b9f33343a5e79c58df9a</td>\n </tr>\n <tr>\n <td>apple_idfa_md5</td>\n <td>Apple ID for Advertising (MD5)</td>\n <td>iOS 6+</td>\n <td>bb1e0285fbb97ba83fdb4e72514d62f5</td>\n </tr>\n <tr>\n <td>android_advertiser_id</td>\n <td>Android Advertiser Id</td>\n <td>Android 2.3+</td>\n <td>38400000-8cf0-11bd-b23e-10b96e40000d\n <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\n </tr>\n <tr>\n <td>android_advertiser_id_sha1</td>\n <td>Android Advertiser Id (SHA1)</td>\n <td>Android 2.3+</td>\n <td>4dfaa92388699ac6539885aef1719293879985bfp\n <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\n </tr>\n <tr>\n <td>android_advertiser_id_md5</td>\n <td>Android Advertiser Id (MD5)</td>\n <td>Android 2.3+</td>\n <td>4dfaa92388699ac6539885aef1719293879985bf\n <p><i>To collect this identifier, you need to include Google Play Services SDK in your app</p></i></td>\n </tr>\n</table>\n</div>\n\n<style></style>" } [/block] [block:html] { "html": "<div class=\"isa_info\">\n <strong><font color=\"7d0a80\">Please use raw versions!</font></strong> In order to ensure the most accurate conversion tracking, please use the raw versions (other than the SHA1/MD5) if possible.\n</div> " } [/block] ##About Confirming Impressions Impression beacons MUST be confirmed. PubNative provides a complex mix of demand sources from premium advertisers to performance marketing partners and OpenRTB exchanges. The programmatic buyers are paying only when their impressions are confirmed in real-time. That is why it is essential to confirm the impression beacons in real time. Please be noted as soon as an impression (=creative) is shown to the user and ONLY after the ad has been viewed for 1 second should the impression be confirmed. This is the guideline is in order to respect IAB viewability terms. [block:image] { "images": [ { "image": [ "https://files.readme.io/d3d1ccd-1.png", "1.png", 914, 181, "#bdbcbd" ] } ] } [/block] ## Response Parameters [block:html] { "html": "<div>\n<table>\n <tr>\n <th>Parameter</th>\n <th>Description</th>\n <th>Format</th>\n <th>RTB Compatable</th>\n </tr>\n <tr>\n <td>title</td>\n <td>App title</td>\n <td>string</td>\n <td>YES</td>\n </tr>\n <tr>\n <td>description</td>\n <td>App description</td>\n <td>string</td>\n <td>YES</td>\n </tr>\n <tr>\n <td>cta_text</td>\n <td>Call to action text</td>\n <td>string</td>\n <td>YES</td>\n </tr>\n <tr>\n <td>icon_url</td>\n <td>Icon CDN url</td>\n <td>url</td>\n <td>YES\n <p><i>only 80x80 - Please check if this size\nfits with your tablets or other high resolution screens</p></i></td>\n </tr>\n <tr>\n <td>banner_url</td>\n <td>Banner CDN url</td>\n <td>url</td>\n <td>YES\n <p><i>only 1200x627</p></i></td>\n </tr>\n <tr>\n <td>click_url</td>\n <td>Click through url</td>\n <td>url</td>\n <td>YES</td>\n </tr>\n <tr>\n <td>beacons.type</td>\n <td> </td>\n <td> </td>\n <td>YES</td>\n </tr>\n <tr>\n <td>beacons</td>\n <td> </td>\n <td> </td>\n <td>YES</td>\n </tr>\n <tr>\n <td>revenue_model</td>\n <td>CPA <i>To collect this identifier, you need to include Google Play Services SDK in your app</i>\n <p>CPC<i> Cost Per Click</i></p>\n <p>CPM <i>Cost Per Mille, which is a cost for every 1,000 impressions</i></p></td>\n <td>string</td>\n <td>YES</td>\n </tr>\n<tr>\n <td>points</td>\n <td>CPA campaign <i>1 point = 0.001 USD per 1 conversion</i>\n <p>CPM campaign <i>1 point = 0.001 USD per 1,000 impressions</i></p>\n <p>CPM <i>Cost Per Mille, which is a cost for every 1,000 impressions</i></p>\n \t<p>CPC campaign <i>1 point = 0.001 USD per 1 click</i></p>\n <p>if the points value is 0, please notify the PubNative team</p>\n </td>\n <td>integer</td>\n <td>limited</td>\n </tr>\n</table>\n</div>\n\n<style></style>" } [/block] ## Frequently Asked Questions **1. What is impression confirmation?** When the ad is shown, our server must be notified about the impression in order to track the campaign performance correctly. **2. When should be the impression be confirmed?** Whenever a user sees the ad for the first time for a minimum duration of 1 second, the impression beacon should be fired immediately, in real-time. **3. Why is impression confirmation required?** The impression confirmation is a critical part of RTB compliance as well as for the eCPM maximization algorithm and the impression beacon should be triggered when the user actually sees the ad. One of the reasons for this is that campaigns available via RTB are CPM based and if we do not have the impression confirmation at 'seeing' stage, then the revenue will not be counted properly. **4. How is the impression confirmed?** You must send us a GET request to the URL which is specified in impression beacon as follows: [block:code] { "codes": [ { "code": "ads: [\n\tbeacons: [\n\t\t{\n\t\t\ttype: \"impression\",\n\t\t\turl: \"https://t.pubnative.net/tracking/imp?aid=1001000&t=...\"\n", "language": "javascript" } ] } [/block] [block:html] { "html": "<div class=\"isa_info\">\n <strong><font color=\"7d0a80\">Use all available parameters:</font></strong> Please be noted that overall performance depends on the number of submitted targeting criteria. For example, if you decide to share age, gender, location and other demographics in the request, it makes it easier to win impressions for RTB demands; thus, we highly recommend that you send us all the parameters you have available.\n</div> " } [/block] ## Adding Postback If you wish to receive conversion postback of certain parameter you send for example, Click ID, add "&aff_sub={YourClickID}" at the end of API click_url. For example: https ://t.pubnative.net/tracking/click?aid=1001000&t=...&aff_sub={YourClickID} [block:html] { "html": "<div class=\"isa_info\">\n <strong><font color=\"7d0a80\">Note!</font></strong> Please send the PubNative team your postback URL with Click ID parameter. After setting up our team will guide you through the test.\n</div> " } [/block] [block:api-header] { "type": "basic", "title": "Checklist Before Activation" } [/block] After the integration is complete, all that remains is to test the integration and make sure everything is working properly. ## Request *Your request URL includes all required parameters with correct value *Your request URL includes user identifiers. (Android Advertiser ID or Apple IDFA *You are sending requests when user reaches the ad inventory and with planned frequency. *The best practice is to request a maximum of 3 ads per user session. Ads should be refreshed after an event (click or download) or after period of non-engagement. This period depends on the length of user sessions and can be from 1 minute to 3 minutes. ## Response Your app works correctly even when there is no fill (API returns no ads). In case anything is wrong with the app PubNative can disable the fill and later enable it back on when the encountered problems are fixed. ## Impression * You are confirming impressions when the user sees the ad for the first time for a minimum duration of 1 second * You are confirming impressions immediately, in real-time * You shouldn’t confirm impressions twice, even if the user sees the same ad again. One (initial) confirmation is enough ## Clicks * Click happens when the user clicks the advertisement which is linked with the click URL PubNative provides * The click event has to be done by a genuine user and should not be an automated bot or incentivized (rewarded) click * Depending on the type of campaign (app promotion or mobile landing page) the redirect behaviour should be considered * For App promotion campaigns, background redirect (hidden browser/webview) is permitted in order to maintain the user experience * For mobile landing pages, at the end of the redirect you must make sure to either show an internal browser window (better user experience) or send the user directly to the default mobile browser **Please also send your request URL to PubNative team so we can help you to make sure everything is properly setup and ready to go live!** **If you have any questions, don’t hesitate to get in touch: support@pubnative.net** [block:html] { "html": "<div></div>\n\n<style>\n.isa_info {\nmargin: 10px 0px;\npadding:12px;\n}\n\n.isa_info {\n color: #424242;\n background-color: #dcdcdc;\n}\n\n.isa_info i {\n margin:10px 22px;\n font-size:16px;\n vertical-align:middle;\n}\n</style>" } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}