Endpoint
- Supported ad formats: native
- Request method: GET
- Response format: json
How to use?
- 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 )
- 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:
ads: [
{
click_url: "https://t.pubnative.net/tracking/click?aid=1001000&t=..."
User Identifiers
Please use one of the parameters below, listed in a waterfall by the order of the rows.
Name | Description | Platform | Example |
---|---|---|---|
apple_idfa | Apple ID for Advertising | iOS 6+ | 771468523E3346ABAA04E207BBAF094B |
apple_idfa_sha1 | Apple ID for Advertising (SHA1) | iOS 6+ | ee5c19f8cf370b5978f4b9f33343a5e79c58df9a |
apple_idfa_md5 | Apple ID for Advertising (MD5) | iOS 6+ | bb1e0285fbb97ba83fdb4e72514d62f5 |
android_advertiser_id | Android Advertiser Id | Android 2.3+ | 38400000-8cf0-11bd-b23e-10b96e40000d
To collect this identifier, you need to include Google Play Services SDK in your app |
android_advertiser_id_sha1 | Android Advertiser Id (SHA1) | Android 2.3+ | 4dfaa92388699ac6539885aef1719293879985bfp
To collect this identifier, you need to include Google Play Services SDK in your app |
android_advertiser_id_md5 | Android Advertiser Id (MD5) | Android 2.3+ | 4dfaa92388699ac6539885aef1719293879985bf
To collect this identifier, you need to include Google Play Services SDK in your app |
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.
Response Parameters
Parameter | Description | Format | RTB Compatable |
---|---|---|---|
title | App title | string | YES |
description | App description | string | YES |
cta_text | Call to action text | string | YES |
icon_url | Icon CDN url | url | YES
only 80x80 - Please check if this size fits with your tablets or other high resolution screens |
banner_url | Banner CDN url | url | YES
only 1200x627 |
click_url | Click through url | url | YES |
beacons.type | YES | ||
beacons | YES | ||
revenue_model | CPA To collect this identifier, you need to include Google Play Services SDK in your app
CPC Cost Per Click CPM Cost Per Mille, which is a cost for every 1,000 impressions |
string | YES |
points | CPA campaign 1 point = 0.001 USD per 1 conversion
CPM campaign 1 point = 0.001 USD per 1,000 impressions CPM Cost Per Mille, which is a cost for every 1,000 impressions CPC campaign 1 point = 0.001 USD per 1 click if the points value is 0, please notify the PubNative team |
integer | limited |
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:
ads: [
beacons: [
{
type: "impression",
url: "https://t.pubnative.net/tracking/imp?aid=1001000&t=..."
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}
Checklist Before Activation
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: [email protected]