Native Ads API Integration

Get Started with aerNative via API.

Looking for a server-to-server API solution to display native ads?
We've got you covered.


AerServ is excited to launch native ads to the suite of ad types available on the AerServ platform. Native ads allow publishers to create static and video native ad placements on their apps and sites. The initial launch includes support for API based integrations. In future releases, we will continue to add new features including SDK and mediation support.



Unlike traditional ad placements where the ad is delivered as a single package, native ad placements are broken down into separate assets so the publisher can integrate the ad to be consistent with the look and feel of the rest of the page’s content. Consequently, unlike existing ad units such as where a fully contained ad is returned the app or site will need to take the native ad assets and construct an ad while adhering to the guidelines provided by AerServ. Since native ads are intended to blend into the layout and style of an app or site, all apps and sites are potentially a good fit for them, but some good examples of properties that utilize native ads are ones with feeds (news, social, etc.) and ones with articles or lots of content.


Table of Contents


1. Create a Native Ad Placement

Log in to AerServ platform and create an aerNative Ad Placement. 


For step-by-step instructions on how to set up a new Ad Placement see our How to Set Up Ad Placements wiki doc.


Once this step is completed, you will be able to make API calls to AerServ to request a native ad.  For instructions on how to use the AerServ API, please see our Server to Server (S2S) Integration wiki doc.  The native API call supports all the parameters listed.


During integration and testing, we advise using these test placements.

Video: 500000

Banner: 500001

 These test placements will guarantee that a sample native ad is always returned.


2. Integrate Native Placements

Now that you’re set up to make requests for native ads, you can begin integrating native ads to your app or site.  In order to properly integrate, you will need to:

  1. Parse the JSON response for the native ad assets so they are displayed properly.
  2. Implement the tracking requirements. 
Please note: Failure to follow the requirements may result in not getting credit for the served impression.


At a minimum you will receive the following assets from AerServ:

  • img:main or video (img:main for native static or video for video native)
  • data:description
  • data:sponsored by
  • img:icon (optionally displayed)
  • title

You could receive additional assets beyond these. Any asset that has the "required" attribute set to 1 must be displayed as part of your ad unit. Failure to do so could result in the impression not being counted..


2.1 - Native API Response Definitions


When a native ad is returned, you will be provided assets that you will need to parse and display. The following sections provide details and descriptions.


2.1.1 - Native Response Object


The native object is the top level stringified JSON object which identifies a native response.

The stringified native response has the following attributes:

Field Type Description
assets array of objects List of Native Ad's Assets
link object

Destination link. This is the default link object for the ad. Individual assets can also have a link object which should be used instead if provided. If the asset doesn’t have its own link object, this link should be used instead.

imptrackers array of strings

Array of impression tracking URLs expect to return a 1x1 image or 204 response.

jstracker string

Javascript impression tracker.



2.1.2 - Asset Object


The asset object provides the assets needed to construct a native ad.  

A native ad will always return the following minimum assets that must be shown if required is set to 1:

Name Description Provided By Reference
Title Title of the Ad Title Object Section 2.1.3
Icon Icon image of the ad img object with an attribute of ext.aerserv.subtype=1 Section 2.1.5

For video – the video creative

For static – the main image creative

For video – video object

For static – img object with an attribute of ext.aerserv.subtype=3

For video – section 2.1.4

For static – section 2.1.5


Text description of the ad

data object with an attribute of ext.aerserv.subtype=2

Section 2.1.6

Sponsored By

Advertiser sponsoring the ad

data object with an attribute of ext.aerserv.subtype=1

Section 2.1.6


In addition, the native ad provider may have other assets, some of which may be required.  See section 7.6 and 7.7 of the OpenRTB  Native Ads 1.1 specification for the list of possible assets.

In the response, there will be an array of asset objects with different attributes that indicate which asset it is. Note that only one of title, video, img, or data will be present in the asset.


The asset object has the following attributes:

Field Type Description
id int

Unique identifier for the asset within a native response.  For reference purposes only.

required int

Indicates whether the ad provider requires this asset to be displayed.  Note: title, creative, description, and sponsored by should always be displayed regardless of this value.

title object

Object for title assets.  If this is provided, this indicates this asset contains the title.

video object

Object for video assets.  If this is provided, this indicates this asset contains a video and is a video native ad.

img object

Object for image assets.  If this is provided, this indicates this asset contains an image. If there is no video asset returned in along with the image asset, the native ad is static.

link object

Link object for call to actions.  If provided on the asset, this should be used when the asset is clicked.  If there is no link object on the asset, the parent Native link object applies.

data object

Object for description, sponsored by or any other assets beyond the four required by AerServ.  If this is provided, you will need to look into the object to determine what type of data asset this is for.



2.1.3 - Title Object


The title object provides the assets needed to correctly render the title.  


The title object has the following attribute:  

Field Type Description
text string The text of the title.



2.1.4 - Video Object


The video object provides the assets needed to correctly render the video.  


The video object has the following attribute:

Field Type Description
vasttag string VAST XML.



2.1.5 - Img Object


The img object provides the assets needed to correctly render a image.  The ext object will include the type ID referencing Section 7.7 of the OpenRTB1.1 Native specification.  A value of type ID=3 (Main) is required to be shown on native ads. There can be multiple img objects returned.


The img object has the following attributes:

Field Type Description


string URL of image asset.
w int Width of image in pixels.
h int Height of the image in pixels.
ext object Contains the type ID for this image 



2.1.6 - Data Object


The data object is used for both native ad required assets – description and sponsored by– in addition to other assets required by the ad provider. There can be multiple data objects returned.


The data object has the following attributes: 

Field Type Description
label string

The name of the data asset type.  See section 7.6 of the OpenRTB Native Ads 1.1 specification for list of possible values. Note:  “desc” and “sponsored” is required to be shown.



The formatted string of data to be displayed. 

ext object

Contains the type ID for this asset.


2.1.7 - Ext Object


The ext object is used to provide other information provided by AerServ.  This object can be found in any asset that has multiple types including img and data objects.  The primary use is to provide a reference to the type ID listed in section 7.6 and 7.7 of the OpenRTB Native Ads 1.1 specification


The ext object has the following attribute: 

Field Type Description
aerserv object aerNative extension object.


2.1.8 - AerServ Object


The aerserv object is used to provide the type ID of the data asset type.  If this object is provided in an img asset, the value provided references section 7.6 of the OpenRTB Native Ads 1.1 specification.  If this object is provided in a data asset, the value provided references section 7.7 of the OpenRTB Native Ads 1.1 specification.


The aerserv object has the following attribute: 

Field Type Description
subtype int Type ID of the asset.


2.1.9 - Link Object


The link object is used for ‘call to action’ assets, or other links from the Native ad. This object can exist at both the parent native object and any asset object. If the link object is provided on an asset, it should be used when clicked. If the link object is not provided, it should use the native object’s link instead. 


The link object has the following attributes:

Field Type Description
url string Landing URL of the clickable link.
clicktrackers array of strings

List of third-party tracker URLs to be fired on click of the URL. 

fallback string (URL)

Fallback URL for deeplink. To be used if the URL given in the url field is not supported by the device.



2.2 - Tracking Requirements


In order to receive credit for a native ad, it is important to fire tracking events based on the requirements listed below.


2.2.1 - Native Ad Tracking Requirements


  • Fire the impression event when at least 50% of the ad is visible for one continuous second.
  • Fire the click event when the ad is clicked.
  • Do not re-fire any of the events when you scroll out of view and back in.


2.2.2 - Native Video Ad Tracking Requirements


  • The video can start playing when the ad is in view (50% of the video). It should be paused when the criterion is no longer met, e.g. if it is scrolled off the screen. If the application is placed in the background, the video must be paused.
  • Fire the impression event when the ad is in view (50% of the video real estate) and 2 continuous seconds of the ad is played.
  • Fire all quartile events ("start", “firstQuartile”, “midpoint”, “thirdQuartile”, and “complete”) as intended by IAB:
    • Start: this event is used to indicate that an individual creative within the ad was loaded and playback began.
    • FirstQuartile: the creative played for at least 25% of the total duration.
    • Midpoint: the creative played for at least 50% of the total duration.
    • ThirdQuartile: the creative played for at least 75% of the duration.
    • Complete: The creative was played to the end at normal speed.
  • Do not re-fire any of the events if the video is replayed.



3. Guidelines & Best Practices

Check out our Best Practices for Native Ads doc for guidelines to ensure your Native Ad impressions count!



4. Troubleshooting 

4.1 - Sample Native Static Ad Response


Here's a sample JSON response returned for a native static ad:

{"native":"{\"assets\":[{\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":1234,\"title\":{\"text\":\"Native Sample Ad\"},\"required\":1},{\"img\":{\"ext\":{\"aerserv\":{\"subtype\":3}},\"w\":180,\"h\":150,\"url\":\"\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":1235,\"required\":1},{\"data\":{\"ext\":{\"aerserv\":{\"subtype\":1}},\"label\":\"sponsored\",\"value\":\"AerServ\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":1236,\"required\":1},{\"data\":{\"ext\":{\"aerserv\":{\"subtype\":2}},\"label\":\"desc\",\"value\":\"Testing native ads. This is the description.\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":1237,\"required\":1},{\"img\":{\"ext\":{\"aerserv\":{\"subtype\":1}},\"w\":80,\"h\":80,\"url\":\"\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":1238,\"required\":0}],\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"imptrackers\":[\"\", \"\"]}"}


That value of the native key is a stringified JSON object. After being de-stringified, the object can be seen below. 

    "assets": [{
        "link": {
            "clicktrackers": ["", ""],
            "url": ""
        "id": 1234,
        "title": {             "text": "Native Sample Ad"         },         "required": 1     }, {         "img": {             "ext": {                 "aerserv": {                     "subtype": 3                 }             },             "w": 180,             "h": 150,             "url": ""         },         "link": {             "clicktrackers": ["", ""],             "url": ""         },         "id": 1235,         "required": 1     }, {         "data": {             "ext": {                 "aerserv": {                     "subtype": 1                 }             },             "label": "sponsored",             "value": "AerServ"         },         "link": {             "clicktrackers": ["", ""],             "url": ""         },         "id": 1236,         "required": 1     }, {         "data": {             "ext": {                 "aerserv": {                     "subtype": 2                 }             },             "label": "desc",             "value": "Testing native ads. This is the description."         },         "link": {             "clicktrackers": ["", ""],             "url": ""         },         "id": 1237,         "required": 1     }, {         "img": {             "ext": {                 "aerserv": {                     "subtype": 1                 }             },             "w": 80,             "h": 80,             "url": ""         },         "link": {             "clicktrackers": ["", ""],             "url": ""         },         "id": 1238,         "required": 0     }],     "link": {         "clicktrackers": ["", ""],         "url": ""     },     "imptrackers": [“", “"] }




4.2 - Sample Native Video Response


Here's a sample JSON response returned for a native video ad:

{"native":"{\"assets\":[{\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":400004,\"title\":{\"text\":\"Native Sample Ad\"},\"required\":1},{\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":400007,\"video\":{\"vasttag\":\"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"no\\\"?><VAST xmlns:xsi=\\\"\\\" version=\\\"3.0\\\" xsi:noNamespaceSchemaLocation=\\\"vast.xsd\\\"><Ad id=\\\"null\\\"><InLine><AdSystem version=\\\"992-VA\\\">AerServ<\\/AdSystem><AdTitle><![CDATA[null]]><\\/AdTitle><Error><![CDATA[]]><\\/Error><Impression><![CDATA[]]><\\/Impression><Creatives><Creative sequence=\\\"1\\\"><Linear skipoffset=\\\"\\\"><Duration/><TrackingEvents><Tracking event=\\\"start\\\"><![CDATA[]]><\\/Tracking><Tracking event=\\\"firstQuartile\\\"><![CDATA[]]><\\/Tracking><Tracking event=\\\"midpoint\\\"><![CDATA[]]><\\/Tracking><Tracking event=\\\"thirdQuartile\\\"><![CDATA[]]><\\/Tracking><Tracking event=\\\"complete\\\"><![CDATA[]]><\\/Tracking><\\/TrackingEvents><VideoClicks><ClickThrough><![CDATA[]]><\\/ClickThrough><ClickTracking><![CDATA[]]><\\/ClickTracking><\\/VideoClicks><MediaFiles><MediaFile delivery=\\\"progressive\\\" height=\\\"480\\\" type=\\\"video/mp4\\\" width=\\\"640\\\"><![CDATA[]]><\\/MediaFile><\\/MediaFiles><\\/Linear><\\/Creative><\\/Creatives><Extensions><Extension type=\\\"AdServer\\\"><AerServAdSource><![CDATA[aerMarket network for PLC 1000741]]><\\/AerServAdSource><\\/Extension><Extension type=\\\"Value\\\"><AerServPublisherPrice price=\\\"0\\\" pricingModel=\\\"per\\\"/><\\/Extension><\\/Extensions><\\/InLine><\\/Ad><\\/VAST>\"},\"required\":1},{\"data\":{\"ext\":{\"aerserv\":{\"subtype\":1}},\"label\":\"sponsored\",\"value\":\"AerServ\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":400005,\"required\":1},{\"data\":{\"ext\":{\"aerserv\":{\"subtype\":2}},\"label\":\"desc\",\"value\":\"Testing native ads. This is the description.\"},\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"id\":400006,\"required\":1}],\"link\":{\"clicktrackers\":[\"\",\"\"],\"url\":\"\"},\"imptrackers\":[\"\", \"\"]}"}


That value of the native key is a stringified JSON object. After being de-stringified, the object can be seen below.


    "assets": [{
        "link": {
            "clicktrackers": ["", ""],
            "url": ""
        "id": 400004,
        "title": {
            "text": "Native Sample Ad"
        "required": 1
    }, {
        "link": {
            "clicktrackers": ["", ""],
            "url": ""
        "id": 400007,
        "video": {
            "vasttag": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><VAST xmlns:xsi=\"\" version=\"3.0\" xsi:noNamespaceSchemaLocation=\"vast.xsd\"><Ad id=\"null\"><InLine><AdSystem version=\"992-VA\">AerServ<\/AdSystem><AdTitle><![CDATA[null]]><\/AdTitle><Error><![CDATA[]]><\/Error><Impression><![CDATA[]]><\/Impression><Creatives><Creative sequence=\"1\"><Linear skipoffset=\"\"><Duration/><TrackingEvents><Tracking event=\"start\"><![CDATA[]]><\/Tracking><Tracking event=\"firstQuartile\"><![CDATA[]]><\/Tracking><Tracking event=\"midpoint\"><![CDATA[]]><\/Tracking><Tracking event=\"thirdQuartile\"><![CDATA[]]><\/Tracking><Tracking event=\"complete\"><![CDATA[]]><\/Tracking><\/TrackingEvents><VideoClicks><ClickThrough><![CDATA[]]><\/ClickThrough><ClickTracking><![CDATA[]]><\/ClickTracking><\/VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" height=\"480\" type=\"video/mp4\" width=\"640\"><![CDATA[]]><\/MediaFile><\/MediaFiles><\/Linear><\/Creative><\/Creatives><Extensions><Extension type=\"AdServer\"><AerServAdSource><![CDATA[aerMarket network for PLC 1000741]]><\/AerServAdSource><\/Extension><\/Extensions><\/InLine><\/Ad><\/VAST>"
        "required": 1
    }, {
        "data": {
            "ext": {
                "aerserv": {
                    "subtype": 1
            "label": "sponsored",
            "value": "AerServ"
        "link": {
            "clicktrackers": ["", ""],
            "url": ""
        "id": 400005,
        "required": 1
    }, {
        "data": {
            "ext": {
                "aerserv": {
                    "subtype": 2
            "label": "desc",
            "value": "Testing native ads. This is the description."
        "link": {
            "clicktrackers": ["", ""],
            "url": ""
        "id": 400006,
        "required": 1
    "link": {
        "clicktrackers": ["", ""],
        "url": ""
    "imptrackers": [“”, ””]


Was this article helpful?
0 out of 1 found this helpful
Have more questions? Submit a request