You are here: Developers > Ad Request API > Mobile ad requests > Mobile ad request parameters

Mobile ad request parameters

Last updated on January 24, 2018

Each mobile ad requestCommunication from a web browser or app to an ad server to display an ad. contains query string parameters, which are essentially key-value pairs that used to target ads to your ad space. Depending on the type of ad request, some of these parameters are required (such as auid) and others are optional (such as custom variables).

You can include custom key-value pairs in your mobile ad requests. These custom variables may be based on elements such as webpage or app content, a user's registered location, or any other user-specific data. Typically, when you implement custom variables, you should add them to the end of your ad tagA small piece of code that defines the ad space where ads display on a website. It includes parameters that describe the inventory advertising campaigns can target, which may in turn display ads in the ad space.. This way, if the ad tag is truncated for any reason, the optional custom variables will be dropped instead of required parameters, such as the ad unitThe smallest inventory component that represents the space on a site where ads display. ID (auid).

All mobile ad requests must contain either the auid parameter, which specifies one or more ad units that you want to serve ads for, or the pgid parameter, which references the ad unit groupA collection of ad units where related ads display together at the same time. to serve ads for. You can include additional parameters in your OpenX Ad ServerA complete digital advertising platform where publishers sell, manage, and deliver their advertising inventory across all digital formats. mobile ad requests, including custom variables, so that OpenX Ad Server can more effectively target ads to your ad space.

Mobile ad request parameters

Parameter Description Required?
auid

Ad unit ID, which indicates the unique ID for the ad unit where you want to serve an ad.

For example:

  • For a single ad unit: auid=1234
  • For multiple ad units: auid=1234,4321,9876
Yes
url

Indicates the mobile appSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web. store URL or the mobile website URL.

The URL for mobile apps can be HTTP or HTTPS. Non-app store mobile websites should use HTTPS URLs for secure sites.

  • For iOS, it is the App Store URL. For example: url=https://itunes.apple.com/us/app/talking-tom-cat/id377194688?mt=8

  • For Android, it is the Google Play URL. For example: url=https://play.google.com/store/apps/details?id=com.outfit7.talkingtom&hl=en

Yes *

ifa

ID for advertisers (also referred to as "IDFA") with dashes. This is the ID sanctioned for advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. use in the clear (not hashed). This parameter is recommended to be used rather than the equivalent did.adid and did.ia parameters.

For example: 43043FE3-6BA9-4515-8209-6E0AC6AE1ADF

Yes, if available **

lmt

An integer that indicates if the user's mobile device is set for private browsing. If yes, the LMT (limit tracking) flag is passed. This parameter is recommended to be used rather than the equivalent did.adid.enabled and did.iat parameters.

  • 0 (false)
  • 1 (true) The user does not want to be tracked.

Yes, if available **

af

The comma-delimited list of API frameworks supported on the user's device, which can be one or more of the following:

For example: af=3,5

Note that this setting will be overridden by any API framework setting in the ad unit.

Highly recommended
app.bundle Indicates the bundle ID (packageA bundle of targeting criteria for similar inventory segments which you can offer at a predetermined price (typically to facilitate regular sales efforts) and automatically create line items from in OpenX. name) of the app. Highly recommended
app.name Indicates the display name of the app. Highly recommended
ip

Client IP address.

For example: 69.89.31.226

For server-side integrations, highly recommended

lt

Indicates the source of the user's location data, which can be one of the following:

  • 1 (GPS/Location Services)
  • 2 (IP Address)
  • 3 (User Provided, such as a zip code on a website's registration form)

You should send the lt parameter with lat/lon.

For example: lt=1

Important: For 1 to be available for a mobile app, two criteria must be met: the publisherAn account type that represents a business with ad space to sell. must enable sending location and source in the app, and the user must agree to allow location sharing with prompted by the app.

Highly recommended

lat

Indicates the GPS latitude location, in decimal form, of the user. You should send the lt parameter with lat/lon.

For example: lat=37.530676

For mobile app video, required if available.

Highly recommended otherwise

lon

Indicates the GPS longitude location, in decimal form, of the user. You should send the lt parameter with lat/lon.

For example: lon=-122.262447

For mobile app video, required if available.

Highly recommended otherwise

vrw

Video - Rewarded. Indicates the inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. is rewarded video, based on the following:

  • 1 (Yes)
  • 0 (No)

For example: vrw=1

Yes, if rewarded videoA type of linear video ad or ad unit. A user opts into watching a non-skippable video ad in exchange for a non-liquid, in-game reward after viewing the ad. Examples of rewards are: an extra life, continued play, a coupon, a discount code, or something else without monetary value. Rewarded video is not the same as incentivized video.

dr=true

For servers that do not handle sending user cookiesSmall text files sent from a web server to a browser, then returned by the browser each time it logs on to that server. Advertisers use cookies to monitor the number of ads that have been shown to a visitor, while they are used by websites to gauge numbers of unique visitors., this parameter-value combination prevents cookie syncing redirects.

Yes, if mobile app video

vht

Video height. Indicates the expected height dimension of the video ad, in pixels.

Use this as an override for the ad unit setting.

For example: 320

For video, highly recommended

vwd

Video width. Indicates the expected width dimension for the video ad, in pixels.

Use this as an override for the ad unit setting.

For example: 480

For video, highly recommended

net

Indicates the user's network connection type. For a wireless network, use net=wifi.

For mobile app video, highly recommended

openrtb Specifies a string with supply-side OpenRTB data to be passed to OpenX Ad Exchange buyers. No
c.keyvalue=

Custom variable, communicates additional information about the inventory, such as details of app content, inventory location, or user-specific information.

For details, see custom variables in ad requests.

For example: c.gender=1

No
xid

User ID. Indicates the customer-provided user ID, if different from the Device ID.

For example: xid=234hskhjfdkhjs

No
age

Indicates the user's age, in years.

For example: age=35

No
mar

Indicates the user's marital status, which can be one of the following:

  • S (Single)

  • M (Married)

  • D (Divorced)

For example: mar=M

No
eth

Indicates the user's ethnicity, which can be one of the following:

  • 0 (African-American)

  • 1 (Asian)

  • 2 (Hispanic)

  • 3 (White)

  • 4 (Other)

For example: eth=2

No
gen

Indicates the user's gender, which can be one of the following:

  • M (Male)

  • F (Female)

  • O (Other)

For example: gen=F

No
inc

Indicates the user's annual household income, in US Dollars (no commas (,) or periods (.)).

For example: inc=40000

No
cnt

The user's two letter, lower case country code.

For example: cnt=us

No
cty

Indicates the user's city location.

For example: cty=Boston

No
stt

Indicates the user's state location.

For example: stt=california

No
zip

Indicates the US ZIP or postal code for the user.

For example: zip=93222

No
dma

For US locations, indicates the user's Designated Market Area.

For example: dma=803

No
crr

Mobile carrier, which is defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: <MCC>-<MNC>.

Refer to Wikipedia's list of mobile network carriers.

For example: crr=310-410

No
did.adid

(Android only) Indicates the Google advertising ID for the Android OS on the user's device.

For example: did.adid=1be50157-d948-4c62-8814-06b71ac09c3c

Deprecated. Use ifa **
did.adid.enabled

(Android only) Indicates the user has ad tracking either enabled or limited, based on the following:

  • true/1 (Enabled)
  • false/0 (Limited)

For example: did.adid.enabled=true

Note: If a user opts out of interest-based advertising by selecting "limit ad tracking" on their device, the correct value to send OpenX is false/0.

Deprecated. Use lmt **
did.ia

(iOS only) Indicates the Apple IDFA identifier for advertising for Apple iOS6 (or higher) on the user's mobile device.

For example: did.ia=43043FE3-6BA9-4515-8209-6E0AC6AE1ADF

Deprecated. Use ifa **
did.iat

(iOS only) The IFA tracking parameter on the user's device. Indicates the user has ad tracking either enabled or limited, based on the following:

  • true/1 (Enabled)
  • false/0 (Limited)

For example: did.iat=true

Note: If a user opts out of interest-based advertising by selecting "limit ad tracking" on their device, the correct value to send OpenX is false/0.

Deprecated. Use lmt **
did.ai.md5

(Android only) Indicates the MD5 hash of the Android ID for the user's mobile device. Should only be used when did.adid is unavailable.

**
did.ai.sha1

(Android only) Indicates the SHA-1 hash of the Android ID for the user's mobile device. Should only be used when did.adid is unavailable.

**
did.ma.md5

Indicates the MD5 hash of the MAC (Media Access Control) address for the user's mobile device.

**
did.ma.sha1

Indicates the SHA-1 hash of the MAC (Media Access Control) address for the user's mobile device.

**
did.o1

Indicates the Open Device Identification Number (ODIN-1) for the user's mobile device.

For example: did.o1=e1b33694687ded5475f72f996cf025be3dd160fe

**
did.oi

Indicates the OpenUDID for the user's mobile device.

For example:

  • 34a265c3b73e4e (Android)

  • 7a5fab3d942494f7e31be4f4eec0e8156f53c6bf (iOS)

**
did.si

Indicates the SecureUDID for the user's mobile device.

For example: did.si=50647BB4-DA42-49B4-9A8F-541203150654

**
maxbitrate

For a video ad unit, indicates the maximum bitrateThe quantity of data transmitted over time. For video and audio files, quality is measured by the bitrate, similarly to how image quality is measured by resolution. OpenX provides min and max bitrate settings, so that you can determine a balance between video quality (high bitrate) and load time (low bitrate). (in Kbps) of video ads that can serve.

Default: maxbitrate=4000

No

minbitrate

For a video ad unit, indicates the minimum bitrate (in Kbps) of video ads that can serve.

Default: minbitrate=240

No

o

Indicates a random number assigned to the request that helps scope the response from the server.

This ensures that multiple server responses do not collide and is useful if you are writing your own synchronous JavaScript ad tags and do not use the OpenX JavaScript tag library.

For example, when you build your own tag library, send OpenX the required inputs, and parse its output.

This parameter is optional for JavaScript ad tags, mobile ad requests, mobile video ad requests, and video ad requests. It is ignored by other types of ad requests.

No

rc

Refresh count. Once your client initiates a refresh, this indicates the current index in the refresh cycle. This parameter is not initially set in the ad request; however your client application adds it, and sets it with each refresh.

No

rd

Refresh delay (in seconds) for refreshing an iFrame.

This value must be an integer ≥ 1. If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh delay setting for this ad unit (as set when creating or editing the ad unit or its container site).

No
rm

Refresh max. Indicates the maximum number of refreshes for ads displayed through the ad request.

This value must be an integer ≥ 1.

For example, setting this parameter to a value of 5 would result in the display of a total of 6 ads (which includes the initial display of the ad (non-refresh) and the 5 subsequent displays of the ad (refreshes)). If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh max setting for this ad unit, as set creating or editing the ad unit.

No
pgid

Ad unit group ID. Indicates the unique ID for the ad unit group that you want to serve ads for. (This parameter is required if you are requesting ads for a predefined ad unit group).

For example: pgid=537064782

No

* Parameters marked with an asterisk (*) in the Required? column must be present for OpenX Ad Exchange transactions.

** lmt and ifa are preferred for passing device data and recommended to be used rather than the parameters did.adid.enabled, did.ia, did.adid, and did.iat. lmt and ifa can be used for both Android and iOS device types. The following parameters do not have a replacement:

  • did.ai.md5
  • did.ai.sha1
  • did.ma.md5
  • did.ma.sha1
  • did.o1
  • did.oi
  • did.si

Tips

Feedback form