Visit AerServ >>
Follow

Server 2 Server (S2S) API Integration

 
Did you know? 
Some AerServ publishers have seen a 795% Higher Fill Rate and 286% Higher Revenue with the AerServ SDK than with an S2S connection. Try the SDK >>

 

 

  • Display/Banner
  • Video
  • Native

This document describes how you can send server-side ad requests for your mobile application or mobile website to retrieve display/banner ad units. The AerServ ad server is accessible via a simple HTTP request with GET parameters, and will return a response in an easy to use JSON format.

The AerServ Server-to-Server API makes it simple and easy for publishers to connect with our platform and retrieve display/banner ads outside of SDK libraries. To integrate with AerServ through our Server-to-Server API, follow the integration process and technical specifications below.

 

First Steps

  • The first step is to get an aerBanner PLC. This link describes how to obtain one.
  • Then set up a server-side connection to the AerServ API to request and retrieve display/banner ad units using the Test banner PLC listed in the 'Testing' section below.
  • Once the server-side connection is setup and you are able to request and retrieve ads you are good to go live. When you go live make sure to switch out the test PLC with the aerBanner PLC you created in the first step.

 

API Overview

The AerServ Server-to-Server API is designed to be a simple and flexible way to request display/banner ad units for any mobile device. The API accepts simple GET requests, with optional and required parameters in the query string portion of the URL. The parameters must be encoded as key/value pairs using standard HTTP URL-encoding principles.

 

Basic Ad Request

The AerServ server-to-server API endpoint is: http://ads.aerserv.com/as/ 

The basic format of a display/banner server-to-server API request is:

https://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&appname=[APP_NAME]&siteurl=[APP_STORE_URL]&appversion=[APP_VERSION]&network=[NETWORK_CONNECTION]&dnt=[DO_NOT_TRACK]&adid=[UNHASHED_APPLE_IDFA_OR_GOOGLE_ADVERTISING_ID]&lat=[LATITUDE]&long=[LONGITUDE]&ip=[DEVICE_IP_ADDRESS]&make=[DEVICE_MAKE]&model=[DEVICE_MODEL]&os=[DEVICE_OS]&osv=[DEVICE_OS_VERSION]&type=[DEVICE_TYPE]&ua=[ENCODED_USER_AGENT]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&carrier=[CELL_CARRIER]&dw=[DEVICE_SCREEN_WIDTH]&dh=[DEVICE_SCREEN_HEIGHT]&pchain=[PCHAIN]

The text surrounded by brackets [ ] in the example above, is just a placeholder and should be replaced with values prior to sending the request to AerServ.

 

Parameter Overview

 
 PARAMETER  DESCRIPTION EX. VALUE  MOBILE WEB  IN-APP  BANNER/VIDEO  DATA TYPE

adid

Advertising ID - Unhashed Apple IDFA or Google AdId

bbd606b1-32ab-4a1e-
b2aa-5771ad804430

  N/A Required   Both  String
age

Age Demographic Information

 22 Optional Optional  Both Integer
appname Application Name Tien%Len%Online N/A

Required 

* Passing a application name is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the application name from our system and you are not required to pass it in your ad request.

 Both 

 String (encoded)
appversion

Application Version

 1.5 N/A

Optional

 Both

 String

bundleid

App Bundle ID

com.popcap.ios.BejBlitz

 N/A

Required

* Passing a BundleID is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the BundleID from this field and you are not required to pass it in your ad request.

 

 

 Both

 String (encoded)
carrier

Cell carrier

Verizon

 N/A

Optional

 

 Both

 String (encoded)

cb

A unique number generated (guid) to prevent a browser from caching the ad and to ensure a unique call to the server for each ad. This macro helps eliminate discrepancies with outside servers

  

46170

  Required  Required  Both   String
dh Device screen height.  480  Optional  Optional  Both  Integer
dnt

Do Not Track .

Values: 1 - for do not track is enabled, 0 - for allow to track

  1  N/A Required  Both  Boolean
dw

Device screen width.

 320 Optional Optional Both Integer
gdpr

Flag to signify whether the request needs to be treated under gdpr compliance. Omission indicates compliance is unknown

  1,0  Optional  Optional  Both Boolean 
gdpr_consent  

Flag to signify that the end user has given consent to use and process their data. Omission indicates no consent.

  1,0  Optional Optional   Both Boolean 

gender

Gender demographic information.

Values: male, female

 male Optional Optional  Both String

inttype

Device ID Type.

Values: 1 - Mobile/Tablet, 2 - Personal Computer, 3 - Connected TV, 4 - Phone, 5 - Tablet

  1 Optional  Optional  Both Integer

ip

 Client IP Address

123.456.78.9

 Required Required  Both  String

key

 Response type from the server.

1(js), 2(html), 3(for JSON)

 Required Required  Both Integer

lat

 Latitude of Device

33.58

  N/A  Optional  Both  Float

locationsource

Origination of Lat/Long.

Values: 1 - GPS, 2 - Derived from IP

1

 Optional   Optional  Both   Integer
long Longitude of device  117.73  N/A Optional  Both  Float
make Device Make apple Optional Optional  Both String (encoded)
model Device Model iPhone 7 Optional Optional  Both String (encoded)
mraid

MRAID Flag

1 = allow MRAID

0 = do not allow

 1,0 Optional Optional Banner  Boolean
network

The connection your device is using

  wifi, carrier N/A Optional Both   String (encoded)
os Operating System iOS Optional Optional  Both  String (encoded)
osv Operating System Version 10.1 Optional Optional   Both  String
pchain

TAG payment chain.

ex. pchain=[PCHAIN]

 123:xyz Strongly Recommended Strongly Recommended  Both String (encoded)
pl

Indicates whether the call is for a preloaded ad.

Values: 0 designates a call for an ad that will be displayed right away, 1 designates a call made to preload an ad

 1 N/A Required  Both Integer
plc

plc - the PLC number sets the width and height

 1000308 Required  Required  Both Integer
site_appstore_id

Apple appstore ID

 123456789  N/A

Required for IOS

 

Both

 Integer
siteurl  App Store URL

https://itunes.apple.com
/us/app/tienlenonlinefree/

  N/A

Required 

* Passing a app store URL is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the app store URL from our system and you are not required to pass it in your ad request.

Both 

String (encoded)
type 

Device Type.

Values: phone, tablet

  Tablet Optional  Optional  Both  String
ua Client User Agent

Mozilla%2F5.0%20
(Linux%3B%20Android%
204.0.4%3B%20Galaxy%
20Nexus%20Build%
2FIMM76B)

 Required Required  Both String (encoded)
url

The full page URL where advertisement will be displayed

  

http://www.eonline.com
/news/entertainment

 Required N/A  Both String (encoded)
 

vpaid

  

VPAID flag set this if you would like or dislike VPAID ads.

Values: 1=allow, 0=do not allow

 1 Optional  Optional Video  Integer
vph  

Video player height

 480 Optional Optional Video Integer 
vpw Video player width 360 Optional Optional Video Integer
yob Year of birth demographic information 1985  Optional Optional Both Integer

 

Request Requirements:

    • All values passed in the request to AerServ should be URL encoded
    • All values passed (ie IP, User Agent) need to be from the client and not the server
    • The placeholder text (ie [APP_STORE_URL]) should always be removed from the request.
    • If an optional parameter (such as 'Application Version' for In-App) does not have a value then the parameter name should still be sent with a blank value
    • Sending as much data as possible, including the optional parameters, can improve the fill rate
    • XFF header must be included and contain the client IP. Per XFF protocol client IP should be the leftmost IP. IE. X-Forwarded-For: client, proxy1, proxy23
    • If sending an IP through the ad request parameter (i.e. https://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&ip=xxx.xx.xxx), make sure the same IP value in the ad request parameter is contained in the request headers for the IP

  

A sample In App HTML request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000308&key=3&appversion=1.0&network=wifi&dnt=1&adid=bbd606b1-32ab-4a1e-b2aa-5771ad804430&inttype=1&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&locationsource=1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)

 

 

A sample Mobile Web HTML request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000308&key=3&inttype=1&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)

 

Ad Response Formats

 The response returned from the AerServ server-to-server display/banner API with a key value of '3' will be JSON.

 

An example of a JSON response is below: 

     {
     "size": [
           320x50"
     ],
     "id": [
          "18719911d18a741431f1ac5c16f5930998b4a"
     ],
     "content":"<a href=\"https://ads.aerserv.com/cl/
?&plc=1000308&iline=1000266&icid=1000270&wp=1000&rid=ba47e47d-9677-468e-8946-640f29c34625&ntid=18
&adsid=1000313&asplcid=1000310&xch=7&rd=http://www.aerserv.com\" target=\"_blank\"><img src=\
"http://production.cdn.aerserv.com/img/1000270.jpg?1400868487\" width=\"320\" height=\"50\" 
border=\"0\" />",
     "tracker" : "http://127.0.0.1/as/ev/?plc=1002620&iline=1001090&icid=1001001
&wp=0&rid=2c1bdec6-f237-4294-b245-20a6b4bfcd13&ntid=18&adsid=1003981&asplcid=1003361&xch=7&pubprice=0
&buyer=Aerify&ad_source_priority=10&ev=1", "creative_id" : "1007352", "ad_source_name" : 
"Publisher Ad Source Name",
     "publisher_cpm" : 3,
     "impression_events" : [
          "http://www.example.com/tracker/impression"
     ]
     }

 

      • The 'size' element in the JSON is the size of the ad unit
      • The 'id' element in the JSON is a unique ID for this ad request
      • The 'content' element in the JSON is the actual banner/display content which can be rendered
      • The 'tracker' element in the JSON is the impression tracking pixel. The publisher needs to fire this URI when the ad markup is delivered to the page or app in order for AerServ to record it as an impression. The publisher can include it in an html <img> tag and append it to the end of the ad 'content'/'markup' code (see example below).
      • The 'creative_id' element in the JSON is the ID for the creative in the ad which can be used to track the creative and report issues with it to AerServ. The value is a string.
      • The 'ad_source_name' element in the JSON is the name of the ad source that provided the ad 
      • The 'publisher_cpm' element in the JSON is the CPM price paid to the publisher for this ad
      • The 'impression_events' element in the JSON is the tracking pixel for when the ad actually renders/displays on the page. If the publisher has the capability, they need to fire this URI when the ad renders/displays on the page or app. This URI should only fire when the ad is actually displayed on the page and not when the ad code is delivered to the page (the tracker element above is to be fired when the ad code is delivered to the page). If the publisher is not able to fire this URI when the ad actually renders/displays, then they can ignore this field. Regardless of whether the publisher has the ability to fire this URL or not they should still fire the 'tracker' element.

  

Testing

You can test your display/banner server-to-server API connection in a few locations in the AerServ Platform:

  1. The Create Placement Pop-Up
  2. The Edit Placement Page
  3. The Integration Page

On each of these pages, you will see an "Ad Mode" toggle switch that will allow you to toggle between Test Ads and Live Ads. When the toggle is set to "Test," test ads will run through your placement to help verify your integration.

 

 
Don't Forget: When you are done with the verification process, please remember to toggle from "Test" to "Live" to begin receiving live, revenue-generating ads.

 

https://ads.aerserv.com/as/?plc=xxxxxxx&key=3appname=[APP_NAME]&siteurl=[APP_STORE_URL]&appversion=[APP_VERSION]&network=[NETWORK_CONNECTION]&dnt=[DO_NOT_TRACK]&adid=[UNHASHED_APPLE_IDFA_OR_GOOGLE_ADVERTISING_ID]&ip=[DEVICE_IP_ADDRESS]&make=[DEVICE_MAKE]&model=[DEVICE_MODEL]&os=[DEVICE_OS]&osv=[DEVICE_OSV]&type=[DEVICE_TYPE]&ua=[ENCODED_USER_AGENT]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&carrier=[CELL_CARRIER]&dw=[DEVICE_SCREEN_WIDTH]&dh=[DEVICE_SCREEN_HEIGHT]&pchain=[PCHAIN]

 

Error Responses

If no ad can be found a HTTP 200 response will be returned with empty JSON as follows:

{"error" : "No ads available"}

If the server times out (error code is 408) before an ad can be retrieved, then the following JSON will be returned:

{"error" : "408"}

 

 

 

This document describes how you can send server-side ad requests for your mobile application or mobile website to retrieve mobile video ad units. The AerServ ad server is accessible via a simple HTTP request with GET parameters, and will return a response a VAST XML ad unit with JSON.

The AerServ Server-to-Server API makes it simple and easy for publishers to connect with our platform and retrieve video ads outside of SDK libraries. To integrate with AerServ through our Server-to-Server API, follow the integration process and technical specifications below.

 

First Steps

  • The first step is to get an aerVideo PLC. This link describes how to obtain one.
  • The next step is to setup a server-side connection to the AerServ API to request and retrieve video ad units using the Test video PLC listed in the 'Testing' section below.
  • Once the server-side connection is setup and you are able to request and retrieve ads you are good to go live. When you go live make sure to switch out the test PLC with the aerVideo PLC you created in the first step.

 

API Overview

The AerServ Server-Server API is designed to be a simple and flexible way to request mobile video ad units for any mobile device. The API accepts simple GET requests, with optional and required parameters in the query string portion of the URL. The parameters must be encoded as key/value pairs using standard HTTP URL-encoding principles.

 

Basic Ad Request

The AerServ server-to-server API endpoint is: http://ads.aerserv.com/as/ 

The basic format of a video server-to-server API request is:

https://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&appname=[APP_NAME]&siteurl=[APP_STORE_URL]&appversion=[APP_VERSION]&network=[NETWORK_CONNECTION]&dnt=[DO_NOT_TRACK]&adid=[UNHASHED_APPLE_IDFA_OR_GOOGLE_ADVERTISING_ID]&lat=[LATITUDE]&long=[LONGITUDE]&ip=[DEVICE_IP_ADDRESS]&make=[DEVICE_MAKE]&model=[DEVICE_MODEL]&os=[DEVICE_OS]&osv=[DEVICE_OS_VERSION]&type=[DEVICE_TYPE]&ua=[ENCODED_USER_AGENT]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&dw=[DEVICE_SCREEN_WIDTH]&dh=[DEVICE_SCREEN_HEIGHT]&vpw=[VIDEO_PLAYER_WIDTH]&vph=[VIDEO_PLAYER_HEIGHT]&pchain=[PCHAIN]

The text surrounded by brackets [ ] in the example above, is just a placeholder and should be replaced with values prior to sending the request to AerServ.

 

Parameter Overview

 
 PARAMETER  DESCRIPTION EX. VALUE  MOBILE WEB  IN-APP  BANNER/VIDEO  DATA TYPE

adid

Advertising ID - Unhashed Apple IDFA or Google AdId

bbd606b1-32ab-4a1e-
b2aa-5771ad804430

  N/A Required   Both  String
age

Age Demographic Information

 22 Optional Optional  Both Integer
appname Application Name Tien%Len%Online N/A

Required 

* Passing a application name is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the application name from our system and you are not required to pass it in your ad request.

 Both 

 String (encoded)
appversion

Application Version

 1.5 N/A

Optional

 Both

 String

bundleid

App Bundle ID

com.popcap.ios.BejBlitz

 N/A

Required

* Passing a BundleID is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the BundleID from this field and you are not required to pass it in your ad request.

 

 

 Both

 String (encoded)
carrier

Cell carrier

Verizon

 N/A

Optional

 

 Both

 String (encoded)

cb

A unique number generated (guid) to prevent a browser from caching the ad and to ensure a unique call to the server for each ad. This macro helps eliminate discrepancies with outside servers

  

46170

  Required  Required  Both   String
coppa 

Indicates if your app requires COPPA regulation. COPPA imposes certain requirements on operators of websites or online services directed to children under 13 years of age, and on operators of other websites or online services that have actual knowledge that they are collecting personal information online from a child under 13 years of age.

Values: 1=yes , 0=no

  1  Optional  Optional  Both  Boolean
ctm1

Custom value pub would like to pass.

 Foo   Optional  Optional Both   String
ctm2

Custom value pub would like to pass.

  Foo  Optional  Optional  Both  String
dh Device screen height.  480  Optional  Optional  Both  Integer
dnt

Do Not Track .

Values: 1 - for do not track is enabled, 0 - for allow to track

  1  N/A Required  Both  Boolean
dw

Device screen width.

 320 Optional Optional Both Integer
gdpr

Flag to signify whether the request needs to be treated under gdpr compliance. Omission indicates compliance is unknown

  1,0  Optional  Optional  Both Boolean 
gdpr_consent  

Flag to signify that the end user has given consent to use and process their data. Omission indicates no consent.

  1,0  Optional Optional   Both Boolean 

gender

Gender demographic information.

Values: male, female

 male Optional Optional  Both String

inttype

Device ID Type.

Values: 1 - Mobile/Tablet, 2 - Personal Computer, 3 - Connected TV, 4 - Phone, 5 - Tablet

  1 Optional  Optional  Both Integer

ip

 Client IP Address

123.456.78.9

 Required Required  Both  String

key

 Response type from the server.

1(js), 2(html), 3(for JSON)

 Required Required  Both Integer

lat

 Latitude of Device

33.58

  N/A  Optional  Both  Float

locationsource

Origination of Lat/Long.

Values: 1 - GPS, 2 - Derived from IP

1

 Optional   Optional  Both   Integer
long Longitude of device  117.73  N/A Optional  Both  Float
make Device Make apple Optional Optional  Both String (encoded)
model Device Model iPhone 7 Optional Optional  Both String (encoded)
mraid

MRAID Flag

1 = allow MRAID

0 = do not allow

 1,0 Optional Optional Banner  Boolean
network

The connection your device is using

  wifi, carrier N/A Optional Both   String (encoded)
os Operating System iOS Optional Optional  Both  String (encoded)
osv Operating System Version 10.1 Optional Optional   Both  String
pchain

TAG payment chain.

ex. pchain=[PCHAIN]

 123:xyz Strongly Recommended Strongly Recommended  Both String (encoded)
pl

Indicates whether the call is for a preloaded ad.

Values: 0 designates a call for an ad that will be displayed right away, 1 designates a call made to preload an ad

 1 N/A Required  Both Integer
plc

plc - the PLC number sets the width and height

 1000308 Required  Required  Both Integer
site_appstore_id

Apple appstore ID

 123456789  N/A

Required for IOS

 

Both

 Integer
siteurl  App Store URL

https://itunes.apple.com
/us/app/tienlenonlinefree/

  N/A

Required 

* Passing a app store URL is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the app store URL from our system and you are not required to pass it in your ad request.

Both 

String (encoded)
type 

Device Type.

Values: phone, tablet

  Tablet Optional  Optional  Both  String
ua Client User Agent

Mozilla%2F5.0%20
(Linux%3B%20Android%
204.0.4%3B%20Galaxy%
20Nexus%20Build%
2FIMM76B)

 Required Required  Both String (encoded)
url

The full page URL where advertisement will be displayed

  

http://www.eonline.com
/news/entertainment

 Required N/A  Both String (encoded)
 

vpaid

  

VPAID flag set this if you would like or dislike VPAID ads.

Values: 1=allow, 0=do not allow

 1 Optional  Optional Video  Integer
vph  

Video player height

 480 Optional Optional Video Integer 
vpw Video player width 360 Optional Optional Video Integer
yob Year of birth demographic information 1985  Optional Optional Both Integer

  

Request Requirements:

    • All values passed in the request to AerServ should be URL encoded
    • All values passed (ie IP, User Agent) need to be from the client and not the server
    • The placeholder text should always be removed from the request
    • If a parameter (such as 'Application Version' for In App) does not have a value then the parameter name should still be sent with a blank value
    • Sending as much data as possible, including the optional parameters, can improve the fill rate
    • A User Agent must be sent in the headers of the request in order for a valid response to be returned
    • If sending an IP through the ad request parameter (i.e. http://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&ip=xxx.xx.xxx), make sure the same IP value in the ad request parameter is contained in the request headers for the IP

  

A sample In App request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000596&key=3&appname=AerServ%20Test%20App&siteurl=http%3A%2F%2Faerserv.com&bundleid=com.aerserv.www&appdomain=www.aerserv.com&appversion=1.0&network=wifi&dnt=1&adid=bbd606b1-32ab-4a1e-b2aa-5771ad804430&lat=33.58&long=117.73&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)&carrier=Verizon&locationsource=1

  

A sample Mobile Web request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000596&key=3&url=www.aerserv.com&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)

  

Ad Response Formats

The response returned from the AerServ server-to-server video API with a key value of '3' will be JSON.

 

An example of a JSON response is below: 

{
  "size" : "",
  "id" : "e58b2bbc-9cd0-4c1b-9372-39e9b5c757db",
  "content" : "<!--?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?-->AerServ<![CDATA[null]]><![CDATA[http://debug.aerserv.com/sybok/vast_error?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&erc=[ERRORCODE]]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=25&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=18&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://sync.tidaltv.com/genericusersync.ashx?dpid=asrev]]><![CDATA[https://adrta.com/i?clid=ars&paid=ars&dvid=v&caid=1209&plid=1000545&publisherId=183&kv2=&kv3=236A005B-700F-4889-B9CE-999EAB2B605P&kv4=184.189.200.163&kv11=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&kv1=320x480&pricePaid=3000&kv12=1000596&kv5=2&kv23=&kv18=&kv21=&kv24=Mobile_App]]>00:00:15.015<![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=3&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=2&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=5&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=4&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=6&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://www.aerserv.com]]><![CDATA[http://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=7&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P]]><![CDATA[http://d3tplke66d0j4g.cloudfront.net/video/1000545.mp4]]><![CDATA[aerMarket network for PLC 1000596]]></AerServAdSource></Extension><Extension type=\"Value\"><AerServPublisherPrice price=\"0.001\" pricingModel=\"per\"/></Extension></Extensions></InLine></Ad></VAST>",
  "tracker" : "https://events.aerserv.com/as/ev/?pubid=183&appid=796&plc=1000596&iline=1000565&icid=1000545&wp=3000&rid=e58b2bbc-9cd0-4c1b-9372-39e9b5c757db&ntid=18&adsid=1000650&asplcid=1000613&pubprice=1000&pinned=false&xcid=&ev=22&campaignid=1209&vc_user_id=236A005B-700F-4889-B9CE-999EAB2B605P",
  "creative_id" : "1000545",
  "ad_source_name" : "Publisher Ad Source Name",
  "publisher_cpm" : 5,
  "impression_events" : [""]
}

 

      • The 'size' element in the JSON is the size of the ad unit - it may be blank
      • The 'id' element in the JSON is a unique ID for this ad request
      • The 'content' element in the JSON is the actual video VAST XML to be sent to the video player
      • The 'tracker' element in the JSON is impression tracking pixel. This tracking pixel is already contained within the VAST XML so you do not need to use this field.
      • The 'creative_id' element in the JSON is the ID for the creative in the ad which can be used to track the creative and report issues with it to Aerserv. The value is a string.
      • The 'ad_source_name' element in the JSON is the name of the ad source that provided the ad 
      • The 'publisher_cpm' element in the JSON is the CPM price paid to the publisher for this ad
      • The 'impression_events' element in the JSON is the tracking pixel for when the ad actually renders/displays on the page. This field can be ignored for video.

  

Testing

You can test your video server-to-server API connection in a few locations in the AerServ Platform:

  1. The Create Placement Pop-Up
  2. The Edit Placement Page
  3. The Integration Page

On each of these pages, you will see an "Ad Mode" toggle switch that will allow you to toggle between Test Ads and Live Ads. When the toggle is set to "Test," test ads will run through your placement to help verify your integration.

 

 
Don't Forget: When you are done with the verification process, please remember to toggle from "Test" to "Live" to begin receiving live, revenue-generating ads.

 

https://ads.aerserv.com/as/?plc=1000596&key=3&appname=[APP_NAME]&siteurl=[APP_STORE_URL]&appversion=[APP_VERSION]&network=[NETWORK_CONNECTION]&dnt=[DO_NOT_TRACK]&adid=[UNHASHED_APPLE_IDFA_OR_GOOGLE_ADVERTISING_ID]&ip=[DEVICE_IP_ADDRESS]&make=[DEVICE_MAKE]&model=[DEVICE_MODEL]&os=[DEVICE_OS]&osv=[DEVICE_OSV]&type=[DEVICE_TYPE]&ua=[ENCODED_USER_AGENT]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&dw=[DEVICE_SCREEN_WIDTH]&dh=[DEVICE_SCREEN_HEIGHT]

 

Error Responses

If no ad can be found a HTTP 200 response will be returned with empty JSON as follows:

{"error" : "No ads available"}

If the server times out (error code is 408) before an ad can be retrieved, then the following JSON will be returned:

{"error" : "408"}

 

This document describes how you can send server-side ad requests for your mobile application or mobile website to retrieve native ad units. The AerServ ad server is accessible via a simple HTTP request with GET parameters, and will return a response a VAST XML ad unit with JSON.

The AerServ Server-to-Server API makes it simple and easy for publishers to connect with our platform and retrieve native ads outside of SDK libraries. To integrate with AerServ through our Server-to-Server API, follow the integration process and technical specifications below.

 

First Steps

  • The first step is to get an aerNative PLC. This link describes how to obtain one.
  • The next step is to setup a server-side connection to the AerServ API to request and retrieve video ad units using the Test video PLC listed in the 'Testing' section below.
  • Once the server-side connection is setup and you are able to request and retrieve ads you are good to go live. When you go live make sure to switch out the test PLC with the aerNative PLC you created in the first step.

 

API Overview

The AerServ Server-Server API is designed to be a simple and flexible way to request native ad units for any mobile device. The API accepts simple GET requests, with optional and required parameters in the query string portion of the URL. The parameters must be encoded as key/value pairs using standard HTTP URL-encoding principles.

 

Basic Ad Request

The AerServ server-to-server API endpoint is: http://ads.aerserv.com/as/ 

The basic format of a native server-to-server API request is:

https://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&appname=[APP_NAME]&siteurl=[APP_STORE_URL]&appversion=[APP_VERSION]&network=[NETWORK_CONNECTION]&dnt=[DO_NOT_TRACK]&adid=[UNHASHED_APPLE_IDFA_OR_GOOGLE_ADVERTISING_ID]&lat=[LATITUDE]&long=[LONGITUDE]&ip=[DEVICE_IP_ADDRESS]&make=[DEVICE_MAKE]&model=[DEVICE_MODEL]&os=[DEVICE_OS]&osv=[DEVICE_OS_VERSION]&type=[DEVICE_TYPE]&ua=[ENCODED_USER_AGENT]&carrier=[CELL_CARRIER]&locationsource=[LAT_LONG_SOURCE_ORIGINATION]&dw=[DEVICE_SCREEN_WIDTH]&dh=[DEVICE_SCREEN_HEIGHT]&vpw=[VIDEO_PLAYER_WIDTH]&vph=[VIDEO_PLAYER_HEIGHT]&pchain=[PCHAIN]

The text surrounded by brackets [ ] in the example above, is just a placeholder and should be replaced with values prior to sending the request to AerServ.

 

Parameter Overview

 
 PARAMETER  DESCRIPTION EX. VALUE  MOBILE WEB  IN-APP  BANNER/VIDEO  DATA TYPE

adid

Advertising ID - Unhashed Apple IDFA or Google AdId

bbd606b1-32ab-4a1e-
b2aa-5771ad804430

  N/A Required   Both  String
age

Age Demographic Information

 22 Optional Optional  Both Integer
appname Application Name Tien%Len%Online N/A

Required 

* Passing a application name is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the application name from our system and you are not required to pass it in your ad request.

 Both 

 String (encoded)
appversion

Application Version

 1.5 N/A

Optional

 Both

 String

bundleid

App Bundle ID

com.popcap.ios.BejBlitz

 N/A

Required

* Passing a BundleID is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the BundleID from this field and you are not required to pass it in your ad request.

 

 

 Both

 String (encoded)
carrier

Cell carrier

Verizon

 N/A

Optional

 

 Both

 String (encoded)

cb

A unique number generated (guid) to prevent a browser from caching the ad and to ensure a unique call to the server for each ad. This macro helps eliminate discrepancies with outside servers

  

46170

  Required  Required  Both   String
coppa 

Indicates if your app requires COPPA regulation. COPPA imposes certain requirements on operators of websites or online services directed to children under 13 years of age, and on operators of other websites or online services that have actual knowledge that they are collecting personal information online from a child under 13 years of age.

Values: 1=yes , 0=no

  1  Optional  Optional  Both  Boolean
ctm1

Custom value pub would like to pass.

 Foo   Optional  Optional Both   String
ctm2

Custom value pub would like to pass.

  Foo  Optional  Optional  Both  String
dh Device screen height.  480  Optional  Optional  Both  Integer
dnt

Do Not Track .

Values: 1 - for do not track is enabled, 0 - for allow to track

  1  N/A Required  Both  Boolean
dw

Device screen width.

 320 Optional Optional Both Integer
gdpr

Flag to signify whether the request needs to be treated under gdpr compliance. Omission indicates compliance is unknown.

  1,0  Optional  Optional  Both Boolean 
gdpr_consent  

Flag to signify that the end user has given consent to use and process their data. Omission indicates no consent.

  1,0  Optional Optional   Both Boolean 

gender

Gender demographic information.

Values: male, female

 male Optional Optional  Both String

inttype

Device ID Type.

Values: 1 - Mobile/Tablet, 2 - Personal Computer, 3 - Connected TV, 4 - Phone, 5 - Tablet

  1 Optional  Optional  Both Integer

ip

 Client IP Address

123.456.78.9

 Required Required  Both  String

key

 Response type from the server.

1(js), 2(html), 3(for JSON)

 Required Required  Both Integer

lat

 Latitude of Device

33.58

  N/A  Optional  Both  Float

locationsource

Origination of Lat/Long.

Values: 1 - GPS, 2 - Derived from IP

1

 Optional   Optional  Both   Integer
long Longitude of device  117.73  N/A Optional  Both  Float
make Device Make apple Optional Optional  Both String (encoded)
model Device Model iPhone 7 Optional Optional  Both String (encoded)
mraid

MRAID Flag

1 = allow MRAID

0 = do not allow

 1,0 Optional Optional Banner  Boolean
network

The connection your device is using

  wifi, carrier N/A Optional Both   String (encoded)
os Operating System iOS Optional Optional  Both  String (encoded)
osv Operating System Version 10.1 Optional Optional   Both  String
pchain

TAG payment chain.

ex. pchain=[PCHAIN]

 123:xyz Strongly Recommended Strongly Recommended  Both String (encoded)
pl

Indicates whether the call is for a preloaded ad.

Values: 0 designates a call for an ad that will be displayed right away, 1 designates a call made to preload an ad

 1 N/A Required  Both Integer
plc

plc - the PLC number sets the width and height

 1000308 Required  Required  Both Integer
site_appstore_id

Apple appstore ID

 123456789  N/A

Required for IOS

 

Both

 Integer
siteurl  App Store URL

https://itunes.apple.com
/us/app/tienlenonlinefree/

  N/A

Required 

* Passing a app store URL is required. However, if you have set up your app in the AerServ platform using an Apple App Store URL or Google Play Store URL,AerServ can extract the app store URL from our system and you are not required to pass it in your ad request.

Both 

String (encoded)
type 

Device Type.

Values: phone, tablet

  Tablet Optional  Optional  Both  String
ua Client User Agent

Mozilla%2F5.0%20
(Linux%3B%20Android%
204.0.4%3B%20Galaxy%
20Nexus%20Build%
2FIMM76B)

 Required Required  Both String (encoded)
url

The full page URL where advertisement will be displayed

  

http://www.eonline.com
/news/entertainment

 Required N/A  Both String (encoded)
 

vpaid

  

VPAID flag set this if you would like or dislike VPAID ads.

Values: 1=allow, 0=do not allow

 1 Optional  Optional Video  Integer
vph  

Video player height

 480 Optional Optional Video Integer 
vpw Video player width 360 Optional Optional Video Integer
yob Year of birth demographic information 1985  Optional Optional Both Integer

  

Request Requirements:

    • All values passed in the request to AerServ should be URL encoded
    • All values passed (ie IP, User Agent) need to be from the client and not the server
    • The placeholder text (ie. [APP_STORE_URL]) should always be removed from the request
    • If a parameter (such as 'Application Version' for In App) does not have a value then the parameter name should still be sent with a blank value
    • Sending as much data as possible, including the optional parameters, can improve the fill rate
    • XFF header must be included and contain the client IP. Per XFF protocol client IP should be the leftmost IO.
      • Ie. X-Forwarded-For: client, proxy1, proxy23
    • If sending an IP through the ad request parameter (i.e. http://ads.aerserv.com/as/?plc=[PLACEMENT]&key=3&ip=xxx.xx.xxx), make sure the same IP value in the ad request parameter is contained in the request headers for the IP

  

A sample In App HTML request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000596&key=3&appname=AerServ%20Test%20App&siteurl=http%3A%2F%2Faerserv.com&bundleid=com.aerserv.www&appdomain=www.aerserv.com&appversion=1.0&network=wifi&dnt=1&adid=bbd606b1-32ab-4a1e-b2aa-5771ad804430&lat=33.58&long=117.73&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)&carrier=Verizon&locationsource=1

  

A sample Mobile Web request with the values inserted would look like the following:

https://ads.aerserv.com/as/?plc=1000596&key=3&url=www.aerserv.com&ip=123.456.78.9&make=Apple&model=iPhone4&os=iOS&osv=7.1&type=phone&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.0.4%3B%20Galaxy%20Nexus%20Build%2FIMM76B)

  

Native Ads API Integration

For more details on how to successfully integrate native ads with AerServ, please view our full-length Native Ads API Integration Doc.

  

Testing

Native placements require manual testing. Please reach out to your Publisher Account Manager to test your native placements.

 

Error Responses

If no ad can be found a HTTP 200 response will be returned with empty JSON as follows:

{"error" : "No ads available"}

If the server times out (error code is 408) before an ad can be retrieved, then the following JSON will be returned:

{"error" : "408"}

 

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

Comments