API Reference

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.

Integration

Please follow the following guidelines while integrating the PubNative spec. Our spec is based on OpenRTB specifications, and the following information details specs as well as recommended best practices.

Specification

PubNative Exchange allows a mechanism for DSPs and advertisers to bid at an impression level in a first-price or second-price auction model standard. PubNative specification aligns with OpenRTB 2.x 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 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.

Pubnative OpenRTB 2.x Spec

Please refer to the "Technical Integration Guide" section for further details and explanations on our spec.

If you have any further questions you can contact [email protected].

Integration Process

Documents

To get started with PubNative, please submit the following:

Once completed, please complete integration using the steps below.

Integration

  1. Build your bidder to comply with the PubNative OpenRTB 2.x spec for
  1. The following fields are required in the bid response
Field NameDescription
Impression IDThe impression ID sent in your bid response (bid_response.id) must match the unique auction ID sent in the bid request (bid_request.id).
NurlWin notification url. Some of PubNative publishers use this for billing reporting.
ImptrackersClient side notification, available only with publishers on PubNative API Version 3. Only required for native bid responses: 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.
Creative ID (crid)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.
bcat / battrPubNative partners are required to support IAB Category blocking and Creative Attribute Blocking. This data will be passed in the ‘bcat’ and ‘battr’ field.

  1. 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.

  2. 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.

  3. 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.
  1. 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.

  1. After customized set up is verified and complete, your integrations AM will turn you live on RTB 2.x with the endpoint of your choice.

  2. One week post-integration, we will do a check-in to review the integration and evaluate how to optimize your account.

Triggering imptrackers, nurl

  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.

🚧

Guidelines for DSPs

  • Always respond to an incoming nurl with a 2xx status code.
  • Post the above step, DSP should count a impression on their end.
  • DSP´s using imptrackers for impression counting have to still respond to nurl with a 2xx status code to avoid impression discrepancies.

Reporting API

You can send a request via reporting API and get your performance stats.

https://dashboard.pubnative.net/api/reports/dsp?account_auth_token={REPORTING_API_KEY}&start_date=DD/MM/YYYY&end_date=DD/MM/YYYY
  • 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)