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).
- 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:
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:
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 personalsparkly Vegas casino
Best Practices