{"_id":"5a2a54a5e25025003c58266e","project":"574ff4bd3fa1870e00889ba6","version":{"_id":"574ff4bd3fa1870e00889ba9","project":"574ff4bd3fa1870e00889ba6","__v":21,"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","5a0322bf044b6f001c236e36"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"category":{"_id":"577f8476a77c700e006a6c52","project":"574ff4bd3fa1870e00889ba6","version":"574ff4bd3fa1870e00889ba9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-08T10:46:14.043Z","from_sync":false,"order":14,"slug":"open-rtb-23-native-extention-version-11","title":"Open RTB 2.3"},"user":"59aebb87fde5ab002740a01c","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-12-08T09:00:21.107Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The full onboarding process of a new bidder to PubNative's platform takes up to a week, but with the collaboration of the DSP it can take only a few days.\n[block:api-header]\n{\n  \"title\": \"Integration\"\n}\n[/block]\nPlease follow the following guidelines while integrating the PubNative spec. Our spec is based on OpenRTB specifications, and the following information details about specs as well as recommended best practices.\n[block:api-header]\n{\n  \"title\": \"Specification\"\n}\n[/block]\nPubNative Exchange allows a mechanism for DSPs and advertisers to bid at an impression level in a standard second price auction model (the winning bid will pay the second highest price in the auction). PubNative specification aligns with OpenRTB 2.3 specifications and may be upgraded to adhere to the newest versions of OpenRTB specs if there are substantial modifications. While we try to adhere to OpenRTB 2.3 to the extent possible, we may require some exchange specific requirements that are optional in the OpenRTB spec, in order to ensure the best buying and selling environment for our DSPs and publishers.\n[block:api-header]\n{\n  \"title\": \"Pubnative OpenRTB 2.3 spec\"\n}\n[/block]\nPlease refer to the Technical Integration section for further details and explanations on our spec and contact demand:::at:::pubnative.net if you have any questions.\n[block:api-header]\n{\n  \"title\": \"Integration Process\"\n}\n[/block]\n## Documents\nTo get started with PubNative, please submit the following:\n* [MNDA](https://drive.google.com/open?id=0B0KrI9pM6fKhQ2FacnVmSUdJazg)\n* [Contract](https://drive.google.com/file/d/0B0KrI9pM6fKhdkszNW9oUUF3UU0/view)\n* [Evaluation form](https://docs.google.com/a/pubnative.net/forms/d/1GMiqOsNNlHEU6UNvlOKigPFbzqKLCT1K9CzU5lO3070/edit)\n* [Credit application](https://drive.google.com/file/d/0B0KrI9pM6fKhUlpJZEdTMlhCVjg/view)\n\nOnce completed, please complete integration using the steps below.\n\n## Integration\n1) Build your bidder to comply with the PubNative OpenRTB 2.3 spec for\n\n* [Standard](http://developers.pubnative.net/docs/technical-integration-standard-banner)\n* [Native](http://developers.pubnative.net/docs/technical-integration-1)\n* [Video](http://developers.pubnative.net/docs/technical-integration-video)\n\n2) The following fields are required in the bid response\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Impression ID\",\n    \"h-0\": \"Field Name\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"The impression ID sent in your bid response (bid_response.id) must match the unique auction ID sent in the bid request (bid_request.id).\",\n    \"1-0\": \"Nurl\",\n    \"1-1\": \"Win notification url. PubNative publishers that are on our API Version 2  use this for billing reporting. See detailed discussion on the implications of nurl vs imptrackers in Section 2.\",\n    \"2-0\": \"Imptrackers\",\n    \"2-1\": \"Client side notification, available only with publishers on PubNative API Version 3. For each bid response, the required ‘imptrackers’ field must contain the impression tracker URL(s) which will be called from the client device directly to the bidder’s servers upon the auction impression/charge event. At a minimum, the impression tracker URL should include substitution macros for ${AUCTION_ID} and ${AUCTION_PRICE}. Please inquire with us for any additional macros.\",\n    \"3-0\": \"Creative ID (crid)\",\n    \"3-1\": \"Unique ID associated with a single creative for a campaign. Creative id’s should not be swapped (i.e. A single id must never have different adomains associated with it) and should also never be 1:1 with an impression.\",\n    \"4-0\": \"bcat / battr\",\n    \"4-1\": \"PubNative partners are required to support IAB Category blocking and Creative Attribute Blocking. This data will be passed in the ‘bcat’ and ‘battr’ field.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n3) To verify that the bid response is valid, please copy/paste the text of a valid and complete bid response from your bidder, save to a txt file, and email directly to your integrations lead.\n\n4) Upon confirming the bid response, we will schedule a 30 min integration call with your team. One member from your tech and ad ops team should be present and the time will be used to answer any questions you have.\n\n5) Complete [PubNative Spend Consent Form](https://docs.google.com/a/pubnative.net/forms/d/1fiLeXQB5S0arxSRskFf0q4ug1vYbphNa-y1fIpk_CwY/edit?usp=drive_web)\n\n6) Testing\n* Create a new test endpoint. Please note that your endpoint will be capped at a maximum of 5% QPS for testing\n* Go live on both iOS and Android campaigns.\n* **IMPORTANT**: Cap spend on your end at $100 max, in order to avoid overspend due to integration issues. While this is a “testing” period, it is live traffic. You will be placing bids and winning inventory on real publisher inventory., so you will be billed for the impressions won during testing as well.  \n\n7) Comparing reports\n* Compare reporting to the data generated from nurl and/or imptrackers (based on your reporting parameter) and verify that reporting is less than 10% discrepant. When you pull reporting, please make sure to send them in UTC.\n* Once reporting alignment is complete, your integrations lead will work with you to customize your bidder setup. Let us know which countries you would like to receive inventory from and whether you have a max QPS your infrastructure can support.\n\n8) After customized set up is verified and complete, your integrations AM will turn you live on RTB 2.3 with the endpoint of your choice.\n \n9) One week post-integration, we will do a check-in to review the integration and evaluate how to optimize your account.\n[block:api-header]\n{\n  \"title\": \"Billing via imptrackers vs nurl\"\n}\n[/block]\nPubnative publisher base is distributed into 2 types based on the API version:\n* API V2\n* API V3\n\nIt is important to understand the difference between the two API versions and its impact on billing.\n\n##Scenario 1: API V2 publishers\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2528ee8-Apiv2.png\",\n        \"Apiv2.png\",\n        804,\n        234,\n        \"#cce0ee\"\n      ]\n    }\n  ]\n}\n[/block]\n1. Publishers using API v2 trigger PN impression tracking URL client side on the event of impression confirmation.\n2. Once PN Ad server receives the PN impression tracking URL, PN triggers `nurl` server side.\n3. We expect the DSP to respond with 2xx response. (Ideally at this step, DSP counts an imp on their side)\n4. Once PN Ad server receives a 2xx response, PN counts an impression.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Guidelines for DSPs (Scenario 1)\",\n  \"body\": \"In case DSP responds with status code other than 2xx, PN will consider it as a failure and retry to get the expected response. During this phase, PN does not count an impression. This is a major cause of impression discrepancy.\"\n}\n[/block]\n##Scenario 2: API V3 publishers\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c04f1a1-APiv3.png\",\n        \"APiv3.png\",\n        804,\n        240,\n        \"#cde0ee\"\n      ]\n    }\n  ]\n}\n[/block]\n1.\t Publishers using API v3 on client side triggers -\n1.1\tPN impression tracking url on the event of impression confirmation.\n1.2\t`nurl` on the event of impression confirmation.\n1.3  \t`imptracker` on the event of impression confirmation.\n2.\tOnce PN receives the PN impression tracking URL, PN counts it as a confirmed impression.\n3. \tOnce DSP receives the `nurl` OR `imptrackers` (triggered client side), DSP counts it as a confirmed impression.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Guidelines for DSPs (Scenario 2)\",\n  \"body\": \"* Always respond to an incoming `nurl` with a 2xx status code.\\n* Post the above step, DSP should count a impression on their end.\\n* DSP´s using imptrackers for impression counting have to still respond to `nurl` with a 2xx status code to avoid impression discrepancies.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<!--<style>\\n.isa_info {\\nmargin: 10px 0px !important;\\npadding:12px !important;\\n}\\n\\n.isa_info {\\n    color: #424242 !important;\\n    background-color: #dcdcdc !important;\\n}\\n\\n.isa_info i {\\n    margin:10px 22px !important;\\n    font-size:16px !important;\\n    vertical-align:middle !important;\\n}\\n</style>-->\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Reporting API\"\n}\n[/block]\nYou can send a request via reporting API and get your performance stats.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://dashboard.pubnative.net/api/reports/dsp?account_auth_token={REPORTING_API_KEY}&start_date=DD/MM/YYYY&end_date=DD/MM/YYYY\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n  * Reporting API Key (account_auth_token) : can be obtained from PubNative dashboard. Please request your PubNative account manager to create an account for dashboard access.\n  * Do not forget to specify the date you wish to see the stats of (format: DD/MM/YYYY)","excerpt":"","slug":"overall-integration-process","type":"basic","title":"Overall Integration Process"}

Overall Integration Process


The full onboarding process of a new bidder to PubNative's platform takes up to a week, but with the collaboration of the DSP it can take only a few days. [block:api-header] { "title": "Integration" } [/block] Please follow the following guidelines while integrating the PubNative spec. Our spec is based on OpenRTB specifications, and the following information details about specs as well as recommended best practices. [block:api-header] { "title": "Specification" } [/block] PubNative Exchange allows a mechanism for DSPs and advertisers to bid at an impression level in a standard second price auction model (the winning bid will pay the second highest price in the auction). PubNative specification aligns with OpenRTB 2.3 specifications and may be upgraded to adhere to the newest versions of OpenRTB specs if there are substantial modifications. While we try to adhere to OpenRTB 2.3 to the extent possible, we may require some exchange specific requirements that are optional in the OpenRTB spec, in order to ensure the best buying and selling environment for our DSPs and publishers. [block:api-header] { "title": "Pubnative OpenRTB 2.3 spec" } [/block] Please refer to the Technical Integration section for further details and explanations on our spec and contact demand@pubnative.net if you have any questions. [block:api-header] { "title": "Integration Process" } [/block] ## Documents To get started with PubNative, please submit the following: * [MNDA](https://drive.google.com/open?id=0B0KrI9pM6fKhQ2FacnVmSUdJazg) * [Contract](https://drive.google.com/file/d/0B0KrI9pM6fKhdkszNW9oUUF3UU0/view) * [Evaluation form](https://docs.google.com/a/pubnative.net/forms/d/1GMiqOsNNlHEU6UNvlOKigPFbzqKLCT1K9CzU5lO3070/edit) * [Credit application](https://drive.google.com/file/d/0B0KrI9pM6fKhUlpJZEdTMlhCVjg/view) Once completed, please complete integration using the steps below. ## Integration 1) Build your bidder to comply with the PubNative OpenRTB 2.3 spec for * [Standard](http://developers.pubnative.net/docs/technical-integration-standard-banner) * [Native](http://developers.pubnative.net/docs/technical-integration-1) * [Video](http://developers.pubnative.net/docs/technical-integration-video) 2) The following fields are required in the bid response [block:parameters] { "data": { "0-0": "Impression ID", "h-0": "Field Name", "h-1": "Description", "0-1": "The impression ID sent in your bid response (bid_response.id) must match the unique auction ID sent in the bid request (bid_request.id).", "1-0": "Nurl", "1-1": "Win notification url. PubNative publishers that are on our API Version 2 use this for billing reporting. See detailed discussion on the implications of nurl vs imptrackers in Section 2.", "2-0": "Imptrackers", "2-1": "Client side notification, available only with publishers on PubNative API Version 3. For each bid response, the required ‘imptrackers’ field must contain the impression tracker URL(s) which will be called from the client device directly to the bidder’s servers upon the auction impression/charge event. At a minimum, the impression tracker URL should include substitution macros for ${AUCTION_ID} and ${AUCTION_PRICE}. Please inquire with us for any additional macros.", "3-0": "Creative ID (crid)", "3-1": "Unique ID associated with a single creative for a campaign. Creative id’s should not be swapped (i.e. A single id must never have different adomains associated with it) and should also never be 1:1 with an impression.", "4-0": "bcat / battr", "4-1": "PubNative partners are required to support IAB Category blocking and Creative Attribute Blocking. This data will be passed in the ‘bcat’ and ‘battr’ field." }, "cols": 2, "rows": 5 } [/block] 3) To verify that the bid response is valid, please copy/paste the text of a valid and complete bid response from your bidder, save to a txt file, and email directly to your integrations lead. 4) Upon confirming the bid response, we will schedule a 30 min integration call with your team. One member from your tech and ad ops team should be present and the time will be used to answer any questions you have. 5) Complete [PubNative Spend Consent Form](https://docs.google.com/a/pubnative.net/forms/d/1fiLeXQB5S0arxSRskFf0q4ug1vYbphNa-y1fIpk_CwY/edit?usp=drive_web) 6) Testing * Create a new test endpoint. Please note that your endpoint will be capped at a maximum of 5% QPS for testing * Go live on both iOS and Android campaigns. * **IMPORTANT**: Cap spend on your end at $100 max, in order to avoid overspend due to integration issues. While this is a “testing” period, it is live traffic. You will be placing bids and winning inventory on real publisher inventory., so you will be billed for the impressions won during testing as well. 7) Comparing reports * Compare reporting to the data generated from nurl and/or imptrackers (based on your reporting parameter) and verify that reporting is less than 10% discrepant. When you pull reporting, please make sure to send them in UTC. * Once reporting alignment is complete, your integrations lead will work with you to customize your bidder setup. Let us know which countries you would like to receive inventory from and whether you have a max QPS your infrastructure can support. 8) After customized set up is verified and complete, your integrations AM will turn you live on RTB 2.3 with the endpoint of your choice. 9) One week post-integration, we will do a check-in to review the integration and evaluate how to optimize your account. [block:api-header] { "title": "Billing via imptrackers vs nurl" } [/block] Pubnative publisher base is distributed into 2 types based on the API version: * API V2 * API V3 It is important to understand the difference between the two API versions and its impact on billing. ##Scenario 1: API V2 publishers [block:image] { "images": [ { "image": [ "https://files.readme.io/2528ee8-Apiv2.png", "Apiv2.png", 804, 234, "#cce0ee" ] } ] } [/block] 1. Publishers using API v2 trigger PN impression tracking URL client side on the event of impression confirmation. 2. Once PN Ad server receives the PN impression tracking URL, PN triggers `nurl` server side. 3. We expect the DSP to respond with 2xx response. (Ideally at this step, DSP counts an imp on their side) 4. Once PN Ad server receives a 2xx response, PN counts an impression. [block:callout] { "type": "warning", "title": "Guidelines for DSPs (Scenario 1)", "body": "In case DSP responds with status code other than 2xx, PN will consider it as a failure and retry to get the expected response. During this phase, PN does not count an impression. This is a major cause of impression discrepancy." } [/block] ##Scenario 2: API V3 publishers [block:image] { "images": [ { "image": [ "https://files.readme.io/c04f1a1-APiv3.png", "APiv3.png", 804, 240, "#cde0ee" ] } ] } [/block] 1. Publishers using API v3 on client side triggers - 1.1 PN impression tracking url on the event of impression confirmation. 1.2 `nurl` on the event of impression confirmation. 1.3 `imptracker` on the event of impression confirmation. 2. Once PN receives the PN impression tracking URL, PN counts it as a confirmed impression. 3. Once DSP receives the `nurl` OR `imptrackers` (triggered client side), DSP counts it as a confirmed impression. [block:callout] { "type": "warning", "title": "Guidelines for DSPs (Scenario 2)", "body": "* Always respond to an incoming `nurl` with a 2xx status code.\n* Post the above step, DSP should count a impression on their end.\n* DSP´s using imptrackers for impression counting have to still respond to `nurl` with a 2xx status code to avoid impression discrepancies." } [/block] [block:html] { "html": "<!--<style>\n.isa_info {\nmargin: 10px 0px !important;\npadding:12px !important;\n}\n\n.isa_info {\n color: #424242 !important;\n background-color: #dcdcdc !important;\n}\n\n.isa_info i {\n margin:10px 22px !important;\n font-size:16px !important;\n vertical-align:middle !important;\n}\n</style>-->" } [/block] [block:api-header] { "title": "Reporting API" } [/block] You can send a request via reporting API and get your performance stats. [block:code] { "codes": [ { "code": "https://dashboard.pubnative.net/api/reports/dsp?account_auth_token={REPORTING_API_KEY}&start_date=DD/MM/YYYY&end_date=DD/MM/YYYY", "language": "http" } ] } [/block] * Reporting API Key (account_auth_token) : can be obtained from PubNative dashboard. Please request your PubNative account manager to create an account for dashboard access. * Do not forget to specify the date you wish to see the stats of (format: DD/MM/YYYY)