Mobile ad request parameters

Last updated on June 14, 2018

Mobile ad request parameters

Video parameters

Deprecated parameters

Tips

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 inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit.. 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 advertiser 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

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

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 (package 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

gdpr

Indicates whether the request is subject to the General Data Protection Regulation (GDPR).

  • 0 = false

  • 1 = true (the request is subject to GDPR)

Highly recommended

gdpr_consent

Indicates that the user has consented to having his or her data collected by the publisherAn account type that represents a business with ad space to sell.'s siteAn OpenX component that represents top-level domains or subdomains and is used to organize ad units. Sites enable you to target and report on inventory performance., as mandated by the GDPR.

The string format, as specified by the IAB, is the daisybit. Example:

BOON9OgOON_SYABABADEAa-AAAARh7______b9_3__7_9uz_Kv_K7Vf7nnG072lPVA9LTOQ6gEaY

See the IAB's GDPR Consent String Specification for more information.

Highly recommended

lt

Use this parameter to indicate the source of your lat and lon parameter values:

  • 1 (GPS/location services)
  • 2 (IP address)
  • 3 (user-provided)

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 publisher 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 device. You should send the lt parameter with lat/lon. This will be passed to buyers as OpenRTB device.geo data (not user.geo).

For example: lat=37.530676

Highly recommended

lon

Indicates the GPS longitude location, in decimal form, of the device. You should send the lt parameter with lat/lon. This will be passed to buyers as OpenRTB device.geo data (not user.geo).

For example: lon=-122.262447

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

User's two-letter, lower case country code. This will be passed to buyers as OpenRTB user.geo data (not device.geo).

For example: cnt=us

No
cty

Indicates the user's city location. This will be passed to buyers as OpenRTB user.geo data (not device.geo).

For example: cty=Boston

No
stt

Indicates the user's state location. This will be passed to buyers as OpenRTB user.geo data (not device.geo).

For example: stt=california

No
zip

Indicates the US ZIP or postal code for the user. This will be passed to buyers as OpenRTB user.geo data (not device.geo).

For example: zip=93222

No
dma

For US locations, indicates the user's Designated Market Area. This will be passed to buyers as OpenRTB user.geo data (not device.geo).

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.ai.md5

(Android only) Indicates the MD5 hash of the Android ID for the user's mobile device.

No
did.ai.sha1

(Android only) Indicates the SHA-1 hash of the Android ID for the user's mobile device.

No
did.ma.md5

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

No
did.ma.sha1

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

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

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

Video parameters

Parameter Description Required?

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

vrw

Video - Rewarded. Indicates the inventory is opt-in video, based on the following:

  • 1 (Yes)
  • 0 (No)

For example: vrw=1

Typically, you do not need to use vrw to indicate that inventory is opt-in videoA type of linear video ad or ad unit associated with mobile apps. A user opts into watching a full-screen, non-skippable video ad in exchange for a non-liquid, in-app reward after viewing the entire ad. Examples of rewards are: access to premium content or features, an extra life, continued play, a coupon, a discount code, or something else without monetary value. Opt-in video is also known as rewarded video, and is not the same as incentivized video., since best practice is to select Is Rewarded in the OpenX ad unit setup and this will enable OpenX to pass this information. However, you can use vrw if you are dynamically passing a mix of opt-in video and interstitialA full-screen ad displayed in content transitions. For example, a video ad that loads between levels of a mobile game. video into a single ad unit.

No

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

Deprecated parameters

The following parameters are deprecated and have replacements, as noted.

Parameter Description Notes
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.o1

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

For example: did.o1=e1b33694687ded5475f72f996cf025be3dd160fe

Deprecated
did.oi

Indicates the OpenUDID for the user's mobile device.

For example:

  • 34a265c3b73e4e (Android)

  • 7a5fab3d942494f7e31be4f4eec0e8156f53c6bf (iOS)

Deprecated
did.si

Indicates the SecureUDID for the user's mobile device.

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

Deprecated

Tips