Ad Integration API

Use the ONE by AOL: Mobile API to easily incorporate ads into your mobile website or application.

The URL Call

ONE by AOL: Mobile is accessed through a server-side URL call (HTTP request). Ad content will then be returned in the specified markup language for inclusion in your site or app.

The URL call is comprised of two parts:

  1. Base URL - The base URL identifies the location of ONE by AOL: Mobile as well as the ad serving end point. Please use http://ads.nexage.com/adServe.
  2. Parameters - The parameter portion of the URL contains attributes which are passed along as part of the ad request. Please reference the following sections for required and optional parameters.

Required Parameters

Required parameters must be passed within the URL to ensure ads are successfully returned. If available, we encourage you to also pass additional subscriber-level data for advanced targeting, as this may help you achieve higher eCPMs.

Mobile Web

The following parameters are REQUIRED for Mobile Web to ensure your ad requests are successfully fulfilled:

Parameter Type Definition Notes
dcn String (32) Distribution Channel Number (also known as Site ID or DCN A unique ONE by AOL: Mobile DCN is assigned to each site you tag. Find this value within the ONE by AOL: Mobile user interface.
pos String (32) position value See Create Ad Placement
Note: position values are case sensitive.
ip String (15) source IP address of the device displaying the ad Demand partners use the IP address to determine the country and carrier of the subscriber and to validate clicks against impressions for billing. Note: ensure you are passing the device IP address and not your internal IP address.
ua String (255) user-agent header of the device into which the ad will be displayed Demand partners use this parameter to identify the handset. If this value is not set, ONE by AOL: Mobile Marketplace will use the 'User-Agent' HTTP header in the request.
Note: ensure the ua parameter is URL encoded.
req(url) String(255) current page URL Used for enhanced analytics and targeting.

Mobile Applications

The following parameters are REQUIRED for Mobile apps to ensure your ad requests are successfully fulfilled:

Parameters Type Definition Notes
dcn String (32) Distribution Channel Number (also known as Site ID or DCN) A unique ONE by AOL: Mobile DCN is assigned to each app you tag. Find the value within the ONE by AOL: Mobile user interface.
pos String (32) position value See Create Ad Placement.
Note: position values are case sensitive.
ip String (15) source IP address of the device displaying the ad Demand partners use the IP address to determine the country and carrier of the subscriber and to validate clicks against impressions for billing.
Note: ensure you are passing the device IP address and not your internal IP address.
ua String (255) user-agent header of the device into which the ad will be displayed Demand partners use this parameter to identify the handset. If this value is not set, ONE by AOL: Mobile will use the 'User-Agent' HTTP header of the request.
Note: ensure the ua parameter is URL encoded.
app String (100) App identifier. App bundle in reverse domain format for Android, numerical App ID for iOS The Android App Store ID can be found in your package name between “id=” and “&hl=en”. Example: com.mobileAOL.game.
The iOS App Store ID can be found in the iTunes URL between “id” and “?mt=8”. Example: 656241300

Key Revenue Generating Parameters

Mobile Web

The following Mobile Web request parameters are optional, but strongly recommended to boost eCPM and revenue.

Parameters Type Definitions Notes
u(id) String(32) Site user ID; any alphanumeric string that uniquely identifies a user.  
req(loc) String(16) location related to the request "x,y", where "x" and "y" are latitude and longitude in numerical form (i.e., south and west are negative)

Mobile Applications

Make sure you have downloaded and installed the ONE by AOL: Mobile SDK specific to your operating system SDK for Android or SDK for iOS.

The following Mobile App request parameters are optional, but strongly recommended to boost eCPM and revenue.

Parameters Type Definition Notes
d(id24) String(40) ID sanctioned for advertising in the clear
ifatrk String(1) Flag to allow or limit ad tracking 1 = ad tracking is fully allowed, 0 = ad tracking must be limited
dnt String(1) Flag for Do Not Track 1 = ad tracking NOT allowed, 0 = ad tracking allowed
req(loc) String(16) Location related to the request "x,y", where "x" and "y" are latitude and longitude in numerical form (i.e., south and west are negative)

Optional Parameters

Mobile Web

The following Mobile Web request parameters are optional, but highly recommended for improved targeting.

Parameter Type Definition Notes
mode String(4) enables test mode for integration “mode=test” indicates test mode. Default or other value=LIVE
cn String(32) page category Up to 4 comma separated content categories as IAB Tier-1 or Tier-2 categories (e.g. IAB1, IAB1-1, etc.).
If sending multiple categories, use the following format: cn=IAB1%2CIAB2
u(dob) String(8) subscriber’s date of birth YYYYMMDD; unknown day=YYYYMM01.  unknown month=YYYY0101
u(age) String(4) subscriber’s age Age in years. alternate to u(dob)
u(gender) String(1) subscriber’s gender Case sensitive gender code as "M", "F", or "O" for male, female, or other
u(eth) String(4) subscriber’s ethnicity "0" (African-American), "1" (Asian), "2" (Hispanic), "3" (White), "4" (Other)
u(marital) String(1) subscriber’s marital status Case sensitive marital status as "S", "M", "D", or "O" for single, married, divorced, or other
u(kids) String(1) kids in household (including user) Case sensitive indicator of any kids within the household (including perhaps the consumer) as “Y” for yes and “N” for no.
u(hhi) String(10) subscriber’s household income Annual income in local base unit (e.g., dollars, euros, yen)
u(dma) String(8) designated Market Area (DMA) DMA by Nielsen Media Research. Must be a number.
u(zip) String(16) customer’s zip/postal code Zip code if USA or postal code of consumer's home base.
u(city) String(32) customer’s city  
u(state) String(16) customer’s state or province 2-letter state abbreviations if USA
u(country) String(4) customer’s country Use the standard 3-letter abbreviations
u(keywords) String(255) keywords pertaining to the consumer's categories of interests Comma separated list
req(keywords) String(255) keywords related to the request Comma separated list. (see "u(keywords)" for keywords that pertain to the consumer)
req(qs) String(255) query parameters Pertaining to current page 
req(ref) String(255) referrer URL
req(search) String(255) search string used to arrive at page Search term for search-based ads
req(zip) String(16) zip /postal code of the request  
req(ac) String(16) telephone area code  
h(…) String(255) HTTP headers from the device Header name should be in the parentheses [i.e.:  h(x-forwarded-for)]
loctype String(4) Location source "1" (GPS), "2" (IP address), "3" (user reported), "4" (non-GPS location services), and "5" (regional centroid)
grp String(40) Impression Group Alpha-numeric (lower-case) ID that matches an existing configured Impression Group.
coppa String(1) COPPA restricted "0" (No) or "1" (Yes), whether this impression is subject to COPPA restrictions.
secure String(1) Secure flag For specifying the ad content is secure vs non-secure (https vs http). 0 = non-secure, 1 = secure, and any other value or its omission indicates unknown

Mobile Applications

The following Mobile App request parameters are optional, but highly recommended for improved targeting.

Parameter Type Definition Notes
mode String(4) enables test mode for integration “mode=test” indicates test mode. Default or other value=LIVE
cn String(32) Page/app category Up to 4 comma separated content categories as IAB Tier-1 or Tier-2 categories (e.g. IAB1, IAB1-1, etc.). If sending multiple categories, use the following format:
cn=IAB1%2CIAB2
mraid String(4) Level of MRAID support as "1", "2", and "3".  
d(hwv) String(32) Device hardware version intended to augment device make and model, mostly for iPhone (e.g. 4, 4S, 5, 5S, 5C)
d(ppi) String(16) Device screen density as pixels per inch (PPI). This will be a number (e.g. 326 for iPhone 4 and 5)
u(id) String(32) publisher-defined or anonymous user identifier Alphanumeric or hashed string that enables correlation of requests by user
u(dob) String(8) subscriber’s date of birth YYYMMDD; unknown day=YYYYMM01. unknown month=YYYY0101
u(age) String(4) subscriber’s age Age in years. alternate to u(dob)
u(gender) String(1) subscriber’s gender Case sensitive gender code as "M", "F", or "O" for male, female, or other
u(eth) String(4) subscriber’s ethnicity "0" (African-American), "1" (Asian), "2" (Hispanic), "3" (White), "4" (Other)
u(marital) String(1) subscriber’s marital status Case sensitive marital status as "S", "M", "D", or "O" for single, married, divorced, or other
u(kids) String(1) kids in household (including user) Case sensitive indicator of any kids within the household (including perhaps the consumer) as “Y” for yes and “N” for no.
u(hhi) String(10) subscriber’s household income Annual income in local base unit (e.g., dollars, euros, yen)
u(dma) String(8) designated Market Area (DMA) DMA by Nielsen Media Research. Must be a number.
u(zip) String(16) customer’s zip/postal code Zip code if USA or postal code of consumer's home base.
u(city) String(32) customer’s city  
u(state) String(16) customer’s state or province 2-letter state abbreviations if USA
u(country) String(4) customer’s country Use the standard 3-letter abbreviations.
u(keywords) String(255) keywords pertaining to the consumer's categories of interests Comma separated list
req(keywords) String(255) keywords related to the request Comma separated list. (see "u(keywords)" for keywords that pertain to the consumer)
req(qs) String(255) query parameters Pertaining to current page
req(ref) String(255) referrer URL URL that caused navigation to current page
req(search) String(255) search string used to arrive at page Search term for search-based ads
req(zip) String(16) zip /postal code of the request  
req(url) String(255) current page URL Used for enhanced analytics and targeting
req(ac) String(16) telephone area code  
h(…) String(255) HTTP headers from the device Header name should be in the parentheses [e.g.  h(x-forwarded-for)]
loctype String(4) Location source "1" (GPS), "2" (IP address), "3" (user reported), "4" (non-GPS location services), and "5" (regional centroid)
grp String(40) Impression Group Alpha-numeric (lower-case) ID that matches an existing configured Impression Group.
coppa String(1) COPPA restricted "0" (No) or "1" (Yes), whether this impression is subject to COPPA restrictions.
sdk String(32) Display Manager Pass one of the following values in this parameter only if the request is originating from one of these Display Managers: admarvel, adtech, burstly, dfp, mocean, mopub.
v String(16) Display Manager Version Version of the Display Manager passed in the SDK parameter.
secure String(1) Secure flag For specifying the ad content is secure vs non-secure (https vs http). 0 = non-secure, 1 = secure, and any other value or its omission indicates unknown

Always Leverage a Secure Parameter

To make secure connections to the ONE by AOL: Mobile Marketplace ensure the protocol is set to https and the secure flag (secure=1) is included on the API call. This will also guarantee that the markup returned will contain secure markup.

Identifying Unique Users - u(id) parameter for Mobile Web

To send a unique consumer ID, please follow these instructions:

  • For Sites with User Reg Data
    • Pass an MD5 hash of the user name during the ad request
    • For Sites with Anonymous Users
      • Generate a unique ID
        • The unique ID can be up to 32 characters
        • The unique ID can be any combination of the following 64 case-sensitive symbols
          • 0-9
          • a-z
          • A-Z
          • "_"
          • "_"
      • Drop it into a cookie that will not expire
      • Send ONE by AOL: Mobile the unique ID ONLY when it is retrieved from the cookie, not when the unique ID is generated and initially placed into a new cookie

Note: The ONE by AOL: Mobile JavaScript tag handles u(id) automatically. In this case no action is required on your part.

Identifying Unique Devices - d(id) parameters for Mobile Applications

Refer to your OS documentation for how to capture each of the Strongly Recommended Device IDs referenced in the Parameter list above. Please do not modify the case for any Device ID. Please use a plain hash (not salted).

Example HTTP Request

http://ads.nexage.com/adServe?dcn=e123456a78900987a6543aa212345678&pos=header&ua=BlackBerry8 520%2f5.0.0.411+Profile%2fMIDP-2.0+Configuration%2fCLDC- 1.1+VendorID%2f149&ip=206.53.152.24&u(id)=208D24CA0DB4D2AD5BC70B539D8945E8&cn=IAB1&u(zip)=90210&u(age)=18

Key
orange indicates required request parameters
green indicates optional request parameters

Return Markup 

Markup is intended to be inserted into a page as-is and should not be parsed or rewritten in any way (it may change without notification). Below are examples of default markup code for various formats.

Example (Image and Text):

<a href="http://ads.nexage.com/adClick?lid=asdhjh34d9rwasdfsa&amp;id=45623241278978772hjuhf >
<img src="http://adnetworkhostname/images/ad.gif alt="AD"> </a>

<a href="http://ads.nexage.com/adClick?lid=asdhjh34d9rwasdfsa&amp;id=45623241278978772hjuhf>
Click Here!</a>
<img src="http://admax.nexage.com/admax/adEvent.do?
style=”display:none;width:1px;height:1px;border:0;" width="1" height="1" alt="" />

Example (Image only):

<a href="http://ads.nexage.com/adClick?lid=asdhjh34d9rwasdfsa&amp;id=45623241278978772hjuhf ">
    <img src=http://adnetworkhostname/images/ad.png alt="AD">
</a>
<img src="http://ads.nexage.com/admax/adEvent.do?"
style=”display:none;width:1px;height:1px;border:0;" width="1"
height="1" alt="" />

Example (Text only):

<a href="http://ads.nexage.com/adClick?lid=asdhjh34d9rwasdfsa&amp;id=45623241278978772hjuhf">Test Ad
</a>
<img src="http://ads.nexage.com/admax/adEvent.do?"
style=”display:none;width:1px;height:1px;border:0;" width="1"
height="1" alt="" />

Handling Timeouts and Exceptions 

You may set a timeout to abandon the ad request if ad markup is not returned in a timely fashion (often due to networking or other issues). If no ad markup is returned within a few seconds, or a connection cannot be made within a few seconds, then appropriate fall back action will be taken.

The default time out is 1000 milliseconds. Please reach out to your Account Manager if you have a timeout requirement that differs from the default.

Efficiency Tuning

The ONE by AOL: Mobile Marketplace is dedicated to bringing maximum efficiency and returns. We continually upgrade and enhance our algorithms. You control and tune the ONE by AOL: Mobile Marketplace optimization engine as needed. Tuning parameters include eCPM, CTR, response time, etc.

Configuring Network Ad Tag Rules

Your ad source identifies the site or application as publisher content to us. Before ONE by AOL: Mobile can be enabled, each ad source must be configured and rules defined. ONE by AOL: Mobile allows you to use ad sources in our platform as well as those you have already provisioned in other ad networks.

ONE by AOL: Mobile gives you access to more than 225 demand sources—with new demand sources and buyers coming on board every week. Our breadth and depth of demand sources ensures that you’ll get access to the widest variety of monetization opportunities possible through one point of integration.

Let us know if you have a specific relationship with a demand source that is not currently integrated with ONE by AOL: Mobile. We are happy to work with you to enable them on our platform. 

Have more questions? Submit a request