Endpoint
- Supported ad-formats: native
- Request method: GET
- Response format: json
How to use?
- The client generates a GET request to the relevant ad-format and the url param
- The server returns a json response
- The client parses the json according to the ad format
- When the ad is shown, our server must be notified about the impression (check below About Confirming Impressions for more details)
- When user clicks on the ad, the client 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 Impresssions
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?
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.
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 (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 the 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 performed 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]