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

Mobile ad request parameters

Last updated on August 9, 2017

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?
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
age

Indicates the end-user's age, in years.

For example: age=35

No
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
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
c.keyvalue=

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

For details, see custom variables in ad requests.

For example: c.gender=1

No
cnt

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

For example: cnt=us

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
cty

Indicates the end-user's city location.

For example: cty=Boston

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

**
did.adid.enabled

(Android only) Indicates the end-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 an end-user opts out of interest-based advertising by selecting "limit ad tracking" on their device, the correct value to send OpenX is false/0.

**
did.ai.md5

(Android only) Indicates the MD5 hash of the Android ID for the end-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 end-user's mobile device. Should only be used when did.adid is unavailable.

**
did.ia

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

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

**
did.iat

(iOS only) The IFA tracking parameter on the end user's device. Indicates the end-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 an end-user opts out of interest-based advertising by selecting "limit ad tracking" on their device, the correct value to send OpenX is false/0.

**
did.ma.md5

Indicates the MD5 hash of the MAC (Media Access Control) address for the end-user's mobile device. Although not required, it is recommended that you provide this parameter for ad serving within an app.

**
did.ma.sha1

Indicates the sha1 hash of the MAC (Media Access Control) address for the end-user's mobile device. Although not required, it is recommended that you provide this parameter for ad serving within an app.

**
did.o1

Indicates the Open Device Identification Number (ODIN-1) for the end-user's mobile device. Although not required, it is recommended that you provide this parameter for ad serving within an app.

For example: did.o1=e1b33694687ded5475f72f996cf025be3dd160fe

**
did.oi

Indicates the OpenUDID for the end-user's mobile device. Although not required, it is recommended that you provide this parameter for ad serving within an app.

For example:

  • 34a265c3b73e4e (Android)

  • 7a5fab3d942494f7e31be4f4eec0e8156f53c6bf (iOS)

**
did.si

Indicates the SecureUDID for the end-user's mobile device. Although not required, it is recommended that you provide this parameter for ad serving within an app.

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

**
dma

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

For example: dma=803

No

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 appSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web. video

eth

Indicates the end-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 end-user's gender, which can be one of the following:

  • M (Male)

  • F (Female)

  • O (Other)

For example: gen=F

No

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).

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

Yes, if available **

inc

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

For example: inc=40000

No
ip

Client IP address

For example: 69.89.31.226

For server-side integrations, highly recommended
lat

Indicates the GPS latitude location, in decimal form, of the end-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 end-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

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.

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

Yes, if available **

lt

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

  • 1 (GPS/Location Services)
  • 2 (IP Address)
  • 3 (User Provided, e.g. 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 end-user must agree to allow location sharing with prompted by the app.

Highly recommended

mar

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

  • S (Single)

  • M (Married)

  • D (Divorced)

For example: mar=M

No
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

net

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

For mobile app video, highly recommended

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

openrtb Specifies a string with supply-side OpenRTB data to be passed to OpenX Ad Exchange buyers. 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 or a predefined ad unit group).

For example: pgid=537064782

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
stt

Indicates the end-user's state location.

For example: stt=california

No
url

Indicates the mobile app 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 Apple 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*
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

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.

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

xid

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

For example: xid=234hskhjfdkhjs

No
zip

Indicates the US ZIP or postal code for the end-user.

For example: zip=93222

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 did parameters. The double asterisk (**) in the Required? column indicates that at least one of the parameters must be present for OpenX Ad Exchange transactions.

Tips

Feedback form