Introduction
Our Online Native API allows approved partners to retrieve native ad campaigns and their assets that are the most likely to convert in real time in order to display them inside their native ad templates.
Getting your API Key
In order to gain access to our Online Native API, locate and click the ‘Request API’ button, which can be found inside the Native Ad tab, as seen in the picture below:
After requesting access, if your request is accepted, you will receive an e-mail notification with a confirmation notice and your API key will be available in the Native Ad Tab.
The Ad Request Process
In order to get the campaigns and assets from our Online Native API, please follow this simple process:
- Send the request to our API.
- Our platform will evaluate and selects the campaign most likely to convert, and in turn, send you a response with the campaign (or campaigns) and its assets.
- Process our platform’s response, and display the ad to your user.
Building a Request
All requests should be made by using POST:
https://sdk.persona.ly/api/native?placementId=PLACEMENTID&apiKey=APIKEY
Both placementId and apiKey are mandatory and can be found in your dashboard, inside the Native Ad tab.
Size, creative type, and additional parameters are to be sent by using POST, in JSON format.
Note that when requesting for campaigns, you may choose to ask for a specific type of creative (image or video, using the creativeType parameter). If you don’t include the creativeType parameter in your request, the response will include creatives in both formats. All of our responses will include the imageLayout object which will contain creatives in three different size groups for you to choose from:
- L (Large) – 1200×627 or 1200×628
- M (Medium) – 300×250
- S (Small) – 320×50 or 300×50
It’s also possible to send the imageLayout parameter with your request, with the desired size group (for example imageLayout = L), to get creatives only from that size group.
The table below details all the fields that can be included in the POST section of the request (mandatory fields are indicated by the tag [r] in their name).
| Name | Description | Examples | Notes |
|---|---|---|---|
| method | Server side or client side | server, client | |
| gaid [m*] | Google advertising ID | 38400000-8cf0- 11bd-b23e- 10b96e40000d | *Mandatory for Android |
| idfa [m*] | Apple's identifier for advertisers | 6D92078A-8246- 4BA4-AE5B- 76104861E7DC | *Mandatory for iOS |
| ip [m*] | The user's IP address | 85.162.123.59 | *Mandatory if using the server side method |
| userAgent [m*] | The user's user agent | Mozilla/5.0 (Linux; Android 6.0.1; SM- G920V Build/MMB29K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.98 Mobile Safari/537.36 | *Mandatory if using the server side method |
| locale | The user's language, in ISO 639 alpha-2 format | EN, DE | |
| uid | Your internal user id | ||
| adCount | The number of campaigns you wish to receive in the response | 3, 4 | If empty, the default is 1 |
| creativeType | In case you want to get a specific creative type, specify it here | image, video | If empty, the reply will include all types |
| imageLayout | The ad placement's size group (described below) | L, M, S | If filled, the response will include only the creatives from that size group |
| iconOnly | Request to get only the app icons, and no other creatives | true | If set to true, only the app logo url will be provided, without a creative |
- Note – If there are no creatives available in one of the size groups, it will return ‘null’. Below is an example of how the imageLayout object:
{
S: {
url: '1.png',
width: 300,
height: 50,
},
M: {
url: '2.png',
width: 300,
height: 250,
},
L: {
url: '3.png',
width: 1200,
height: 627,
},
}
Response Parameters
The table below details all the fields that can be included in a response from our API:
| Name | Description | Example |
|---|---|---|
| AdID | The campaign's ID | 598c1ed1476e251000 b7ecf5 |
| App Name | The name from the relevant app store | Popogame |
| App_ID | The Apple app ID or Android Package ID | com.popocompany.popogame |
| App Landing page | The link to the relevant app store | https://play.google.com/store/apps/ detailsid=com.gramgames.london.bounzy &hl=en |
| rating | The app's rating from the app store | 4.5 |
| categories | The app's relevant categories on the app store | Games, Social |
| reviews | The number of reviews from the app store | 24232 |
| appDeveloper | The name of the developer from the relevant store | Machine Zone, King, War Gaming |
| appDescription | The description of the app from the relevant store | ave fun challenging your friends and enemies in the hottest trivia game! Let our friendly spinner wheel, Willy, select which questions you’ll answer from six... |
| appIcon | The URL path to the app's icon | https://assets.persona.ly/static/Gardenscape_ 9801402c57b442a019fae552a80cd2b4.png |
| hqVideoPath | When using video: the URL path to the high quality video ad | https://assets.persona.ly/videos/p720_ Facebook_Facebook_Video_0417_Portrait_ Converted.mp4 |
| lqVideoPath | When using video: the URL path to the low quality video ad | https://assets.persona.ly/videos/p480_ Facebook_Facebook_Video_0417_Portrait_ Converted.mp4 |
| imagePath | When using image: the URL path to the image ad | https://assets.persona.ly/static/Gardenscape_ 300x250_GS_image001_en.jpg |
| CTA | The text for the ad's call to action button | Install Now |
Beacons
The table below details all the URL paths for reporting purposes, included in the final section of the response from our API, as well as the URL path for our favicon and privacy policy, when required:
| Name | Description | Example |
|---|---|---|
| trackingUrl | The link to the app store with Persona.ly's tracking | https://sdk.persona .ly/api/impressions /59a41b3865eebe1 100d5f6a3/native/c lick |
| impressionUrl | To be fired when the ad is displayed | https://sdk.persona .ly/api/impressions /59a41b3865eebe1 100d5f6a3/native |
| privacyPolicy{"url", "image"} | Link to our favicon and our privacy policy. |
Example Response
Below is an example of a requests body and a response from our API:
BODY { "method": "server", "ip": "204.152.203.156", "userAgent": " Mozilla/5.0 (Linux;Android 6.0.1; SM-G920V Build/MMB29K)AppleWebKit/537.36(KHTML, like Gecko)Chrome/52.0.2743.98Mobile Safari/537.36", "gaid": "38400000-8cf011bd-b23e-10b96e40000d", "uid": "test_native_user_id", "locale": "us", "creativeType": "image" "adCount": 3,
RESPONSE { "status": "success", "result": [ { "info": { "adId": "599e78b288ba691200574e5c", "appName": "Art of Conquest (AoC)", "appId": "com.lilithgame.sgame.gp.oss", "landingPage": "https://play.google.com/store/apps/details?id=com.lilithgame.sgame.gp.oss&hl=en", "rating": 4.3, "reviews": 50967, "categories": [ "Strategy" ], "appDeveloper": "Lilithgames", "appDescription": "Featured globally by Google Play!◆ \"This new strategy game gives you full control in a world full..." }, "creative": { "appIcon": "https://assets.persona.ly/static/Art_of_Conquest_03d2baa465d9441e6862760276c49ebe1503478219.png", "imageLayout": { "L": { "id": "59bbd82d07132b120004421c", "url": "https://assets.persona.ly/static/Art_of_Conquest_W14-B-__-1-__.jpg", "width": 1200, "height": 628 } }, "cta": "Install now" }, "impressionUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef5/native", "trackingUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef5/native/click", "privacyPolicy": { "url": "https://persona.ly/privacy/", "image": "https://assets.persona.ly/Favicon.png" } }, { "info": { "adId": "59bfdc2ef7afb61200c96e2e", "appName": "Jackpot Magic Slots™: Vegas Casino & Slot Machines", "appId": "com.bigfishgames.jackpotcityslotsf2pgoogle", "landingPage": "https://play.google.com/store/apps/details?id=com.bigfishgames.jackpotcityslotsf2pgoogle&hl=en", "rating": 4.6, "reviews": 63186, "categories": [ "Casino" ], "appDeveloper": "Big Fish Games", "appDescription": "Free slot machines fun! This slot machine app is your personal 🍸 sparkly Vegas casino 🍸. Spinni..." }, "creative": { "appIcon": "https://assets.persona.ly/static/Jackpot_Magic_Slots_a62f0c23f9143e072259fdba5c68bd231505729826.png", "imageLayout": { "M": { "id": "59e8cfb4b06aae1100db4eb4", "url": "https://assets.persona.ly/static/Jackpot_Magic_Slots_147007_300x250_V1A_That-Blue-Flame-tho-min.jpg", "width": 300, "height": 250 }, "S": { "id": "59e8cfb5b06aae1100db4ec8", "url": "https://assets.persona.ly/static/Jackpot_Magic_Slots_147007_320x50_V1A_That-Blue-Flame-tho-min.jpg", "width": 320, "height": 50 } }, "cta": "Install now" }, "impressionUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef6/native", "trackingUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef6/native/click", "privacyPolicy": { "url": "https://persona.ly/privacy/", "image": "https://assets.persona.ly/Favicon.png" } }, { "info": { "adId": "59d7628bf1bdcf110057e095", "appName": "InboxDollars", "appId": "com.mentormate.android.inboxdollars", "landingPage": "https://play.google.com/store/apps/details?id=com.mentormate.android.inboxdollars&hl=en", "rating": 4.3, "reviews": 76966, "categories": [ "Entertainment" ], "appDeveloper": "InboxDollars", "appDescription": "InboxDollars (www.inboxdollars.com) is the mobile and online loyalty club that pays cash! Members..." }, "creative": { "appIcon": "https://assets.persona.ly/static/InboxDollars_-_CPE_d4a60e8cde6f7feee46d23363375d9521507285431.png", "imageLayout": { "L": { "id": "59e8d24db06aae1100db6475", "url": "https://assets.persona.ly/static/InboxDollars_-_CPE_1200x628-green.jpg", "width": 1200, "height": 628 }, "M": { "id": "59e8d24db06aae1100db6472", "url": "https://assets.persona.ly/static/InboxDollars_-_CPE_300x250-green.jpg", "width": 300, "height": 250 }, "S": { "id": "59e8d24fb06aae1100db6492", "url": "https://assets.persona.ly/static/InboxDollars_-_CPE_320x50-green.jpg", "width": 320, "height": 50 } }, "cta": "Install now" }, "impressionUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef7/native", "trackingUrl": "https://sdk.persona.ly/api/impressions/59ef2c504dfcd91100ec6ef7/native/click", "privacyPolicy": { "url": "https://persona.ly/privacy/", "image": "https://assets.persona.ly/Favicon.png" } } ] }
Best Practices