AppLovin oRTB Specification

AppLovin RTB supports the OpenRTB 2.5 API on ad requests from apps that MAX mediates. This document describes the OpenRTB integration with AppLovin for SDK bidders and DSPs and details any feature differences between the OpenRTB 2.5 spec and the AppLovin RTB spec.

GDPR non-consent and CCPA do-not-sell requests are not supported and will not be sent in the bid stream.

Protocol Details

Bid Requests
AppLovin RTB buyers receive bid requests in HTTP POST format. AppLovin recommends that you use HTTP so as to avoid latency.
HTTP Keep-Alive
AppLovin RTB buyers should enable persistent connection handling. Set max keep-alive to at least five minutes.
Compressed/gzip oRTB
AppLovin RTB requires compression for efficiency. Adhere to OpenRTB API Specification version 2.5 section 2.4: Data Encoding.

Bid Regions

The AppLovin RTB servers cover four geographical regions:

  • ASIA-PACIFIC: Hong Kong, Tokyo
  • EUROPE: Amsterdam
  • US-EAST: New York, Washington
  • US-WEST: San Francisco, San Jose

Endpoints

DSP buyers and SDK bidders can specify up to one endpoint per region. All requests from the respective region will be routed to that endpoint.

Supported Ad Formats

AppLovin RTB supports mobile in-app ads only; it does not support desktop or web ad serving. The ad formats AppLovin RTB supports are banners, medium rectangles (MRECs), native ads, interstitials, and rewarded ads.

Acceptable MIME types include:

ad format MIME type
MRAID, HTML, MREC text/html
Native ads image/png, image/jpeg, image/gif
VAST video/mp4

Acceptable MRAID and VAST versions include those shown in the list below. However, there are limitations. For example, AppLovin RTB does not support calendar API events from MRAID.

  • MRAID 1.0
  • MRAID 2.0
  • MRAID 3.0
  • VAST 2.0
  • VAST 3.0
  • VAST 4.0
  • VAST 4.1
  • VAST 4.2

There is additional information further down on this page concerning MRAID, native ads, and VAST support.

Supported Ad Sizes

AppLovin RTB supports the following ad sizes:

object sizes
Video object (VAST)
  • 320×480
  • 480×320
  • 768×1024
  • 1024×768
  • 1920×1080 (Connected TV)
Banner object (HTML, MRAID, MREC)
  • 300×250
  • 320×50
  • 320×480
  • 480×320
  • 768×1024
  • 1024×768
Native object specific instructions below

Exchange Currency

AppLovin RTB Exchange supports only USD. It ignores the currency attribute cur.

Auction Type

MAX auction runs on a first-price basis. AppLovin expects bidders to pay the CPM amount they bid in full.

Blocked Creative Types

AppLovin RTB blocks the following creative types:

  • Adobe Flash
  • Audio Ad (Auto-Play)
  • Audio Ad (User Initiated)
  • Expandable (User Initiated — Rollover)
  • Pop (e.g. Over, Under, or Upon Exit)
  • Provocative or Suggestive Imagery
  • Windows Dialog or Alert Style

If the publisher does not support playable ads, then AppLovin RTB also blocks the following creative types:

  • Expandable (Automatic) [only for non-banner/MREC]
  • Expandable (User Initiated — Click) [only for non-banner/MREC]
  • User Interactive (e.g. Embedded Games)

Blocked Categories

AppLovin RTB blocks the following IAB categories:

  • IAB8-5 (Cocktails/Beer)
  • IAB8-18 (Wine)
  • IAB11-4 (Politics)
  • IAB25 (Non-Standard Content)
  • IAB26 (Illegal Content)

Blocked Ad Types

AppLovin RTB blocks the following ad types:

  • flash
  • iframe
  • XHTML Text Ad

MoPub Marketplace Exchange to AppLovin Exchange Migration: Exchange RTB Breakdown

As DSPs migrate their integration from MoPub Marketplace to the AppLovin Exchange, there will be differences and improvements in some of the key integration features. Below is a comparison of notable RTB feature differences:

Feature MoPub Exchange AppLovin Exchange
Blocked Categories Publishers control which specific blocked categories (bcat) are passed in the bid request, therefore every bid request has a different list of blocked categories. AppLovin sends a preset list of blocked categories.
Banner Impression Width & Height Multiple banner width and height opportunities can be passed per bid request. Only one banner width and height passed per bid request.
Bid Request Companion Ad Object (imp.video.companionad) Supported. Not supported; use companiontype instead.
Pchain Object (bidrequest.source.pchain) Supported. Not Supported.
Substitution Macros Substitution Macro support differs between MPX & ALX. Please refer to MoPub’s macro documentation to compare which are supported. Substitution Macro support differs between MPX & ALX. Please refer to the table of macros to compare which are supported.
Bid Request Publisher Object Bidrequest.publisher.ext not supported. Bidrequest.publisher.ext supported.
Screen Orientation DSPs advised to rely on the bid request width & height passed to determine the device’s orientation. DSP can use the bid request width & height or app.ext.orientation_lock object to determine device orientation.
Device Carrier Passed using a standardized list of carrier codes. Passed using the carrier name written out (e.g. “Verizon”).
Device Hardware Version (device.hwv) Sent for Android only Sent for Android & iOS when available.
Device Geo Extension (device.geo.ext) Not supported. Supported.
Bid Request Bad App (bidrequest.bapp) Supported. Supported upon request, please reach out to your account manager to have this enabled.
SDK Bidder Details Passed in imp.ext.networkids.placementids and imp.ext.networkids.appid. Passed in imp.tagid. Note that network-specific app IDs are not supported.
GDPR Consent Passed in regs.ext.gdpr or user.ext.consent. Passed in user.ext.gdpr, regs.ext.consent, or regs.ext.gdpr.
Video Skip Request Object Supported. Not supported.
Native Sequence Request Object Supported. Not supported.
User Object MoPub passes user.id, user.ext and can pass other user info such as user.gender, user.keyword, etc. AppLovin passes user.id and user.ext.
Rewarded Object Passed in imp.ext.rewarded. Passed in imp.banner.ext.bannertype, imp.video.ext.videotype

Bid Request

Request Objects

AppLovin RTB bid requests always carry a single impression (this differs from the OpenRTB schema). Each request has exactly one impression object (imp).

Seats

The AppLovin RTB Exchange does not support multiple seats per bidder. It ignores the seat whitelist wseat array.

Bid Request Object

Attribute Description Always Passed?
app Details via an App object (see App Object) about the publisher’s app. yes
at Auction type. If 1 then first-price auction; if 2 then second-price auction (always set to 1 for AppLovin). yes
bapp Block list of applications by their platform-specific, exchange-independent application identifiers. On Android, these are bundle or package names (such as “com.foo.mygame”); on iOS, these are numeric IDs.

This field is sent on an opt-in basis; reach out to your account manager if you want to be enabled for this field.

A maximum of 30 bundles are passed. Bids containing other bundle IDs blocked by publishers will be invalidated and do not participate in the auction.
no
badv Block list of advertisers by their top-level domains (for example, “ford.com”). A maximum of 30 domains are passed. Bids containing other domains blocked by publishers are invalidated and do not participate in the auction. no
bcat Blocked IAB categories for this impression. See Blocked Categories for a list. no
device Details via a Device object (see Device Object) about the user’s device to which the impression is delivered. yes
ext Placeholder for exchange-specific extensions to OpenRTB. yes
id Unique ID of the bid request yes
imp Array of Impression objects (see Impression Object) representing the impressions offered. Only one impression object will be passed. yes
regs An object that specifies any industry, legal, or governmental regulations in force for this request. no
regs.ext.ccpa Flag indicating if this request is subject to the CCPA regulations, where 0 = no, 1 = yes. yes, if regs is passed
regs.ext.consent Flag indicating if a user has granted consent, where 0 = no, 1 = yes. no
regs.ext.gdpr Flag indicating if this request is subject to the GDPR regulations, where 0 = no, 1 = yes. yes, if regs is passed
regs.ext.us_privacy See OpenRTB Extension for US Privacy no
source An object that provides data about the inventory source and which entity makes the final decision. no
source.ext Placeholder for exchange-specific extensions to OpenRTB. AppLovin passes schain in the extension with subobject ver, complete, and nodes. Please refer to IAB’s spec. yes, if source is passed
tmax Maximum time, in milliseconds, to submit a bid to avoid timeout. Default is 1000ms. yes
user Details about the human user of the device; the advertising audience. no
user.data Contains the name, id, and segment objects. no
user.data.name If applicable, contains data specific to the ad unit, entered by the publisher in the MAX Dashboard. no
user.data.segment Contains the signal field which contains any custom data the SDK bidder collects and passes to MAX SDK via the adapter (e.g. identity token required by the network so that networks or bidders can respond to a bid request). no
user.ext Placeholder for exchange-specific extensions to OpenRTB. no
user.ext.consent 0 if the user did not grant consent; 1 if the user granted consent. no
user.ext.gdpr 0 if the user is not subjected to GDPR; 1 if the user is subjected to GDPR. no
user.id AppLovin-specific device ID for each user within each app. no

App Object

Attribute Description Always Passed?
bundle Application iTunes ID or package name. On Android, this is the package name, for example com.example.app. On iOS, this is the iTunes ID, for example 628677149. no
cat IAB content categories for the Application. See OpenRTB Spec 2.5 List 5.1 for details. yes
content Object that describes the content where the impression will appear for certain requests, including CTV inventory. Aligns to OpenRTB Specification 3.2.16. no
content.ext Placeholder for exchange-specific extensions to OpenRTB, including CTV inventory. no
content.url URL of the content, for buy-side contextualization or review. no
ext Placeholder for exchange-specific extensions to OpenRTB. no
ext.orientation_lock Indicates device orientation: portrait or landscape. no
id Application ID on AppLovin RTB yes
name Application name on AppLovin RTB no
publisher Details about the publisher of the app. yes
publisher.ext Extension object containing additional publisher information. This contains the installed_sdk object which has fields id, and subobject SDK_version with SDK bidder name and version details. For DSP bidders, id will always be "APPLOVIN_EXCHANGE". no
publisher.id The publisher’s AppLovin ID. Publishers should add this value to their app-ads.txt file. yes
publisher.name The publisher’s name. yes
storeurl The URL for the app in the App Store or Google Play Store. Used for app-ads.txt compliance. yes
ver Application version, passed when available. no

Device Object

Attribute Description Always Passed?
carrier (optional) Carrier of device on a cellular network, or ISB of device on WiFi. no
connectiontype Type of connection as per Table 5.22 of the OpenRTB 2.5 spec
0 unknown always pass 0 if the SDK signal is not present.
1 Ethernet if device is directly connected via Ethernet (Android only)
2 Wifi if device is connected via WiFi (Android / iOS)
3 Cellular if device is connected through EDGE, 3G, LTE, etc. (Android / iOS)
no
devicetype The general type of device. Set to 1 for mobile and tablets. See OpenRTB Spec 2.5 Table 5.21for details. no
dnt Specifies whether the “Do Not Track” feature is enabled in the device. If 0, then DNT is set to false. If 1, then DNT is set to true. This parameter is omitted if DNT is not passed by the SDK or on iOS 5 or lower. no
ext Placeholder for exchange-specific extensions to OpenRTB. no
ext.atts (iOS Only) An integer passed to represent the app’s app tracking authorization status, where:
0 not determined
1 restricted
2 denied
3 authorized
no
ext.ifv IDFV of device in that publisher. Only passed when IDFA is unavailable or all zeros. no
geo Location of the device assumed to be the user’s current location defined by a Geo object. yes
h Height of the screen in physical pixels. This may be dependent on the device orientation.

This can differ from banner.h.

no
hwv Hardware version of the device no
ifa (optional) Apple IFA or Google Advertising ID. Google Advertising ID (Android) is lowercase by default; IFA (iOS) is uppercase by default. If raw is not available then this is not passed. Not passed in requests from countries subject to GDPR if the user does not give consent. no
ip IPv4 address of the device. Not passed in requests from countries subject to GDPR if the user does not give consent. yes
ipv6 (optional) IPv6 address of the device. When ipv6 is present, ip is 255.255.255.255 by default. Not passed in requests from countries subject to GDPR if the user does not give consent. no
js 1 if the device supports JavaScript; otherwise 0. (Always 1.) yes
language Browser language, using ISO-639-1-alpha-2. no
lmt “Limit Ad Tracking” signal commercially endorsed (for example by iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines no
make Device make (for example, "Apple") no
mccmnc Mobile Country code and Mobile Network Code concatenated by a dash (e.g. 310-005). See the list of Mobile Country Codes for more details. no
model Model of the device (for example, "iPhone"). iOS will show the full device model name, for example "iPhone 10,1", if known, or just for example "iPhone" if not. Android will have detailed model information such as "SAMSUNG-SM-G900A". no
os Operating system of the device; either "iOS" or "Android". no
osv Operating system version of the device, for example "3.1.2". no
pxratio The ratio of physical pixels to device-independent pixels. A float value from 0.74 through 4.0. yes
ua Unprocessed User-Agent string from HTTP headers no
w Width of the screen in physical pixels. This may be dependent on the device orientation.

This can differ from banner.w.

no

Geo Object

Attribute Description Always Passed?
city City of the device. Based on the IP address & Maxmind database. no
country Country of the device. Based on the IP address & Maxmind database. Passed as country code using ISO-3166-1-alpha-3. no
dma Nielsen DMA code based on IP address. no
ext Placeholder for exchange-specific extensions to OpenRTB. no
ext.isp Internet Service Provider name. no
ext.org Internet Service Provider name. no
ipservice Service or provider used to determine geolocation from IP address if applicable (that is, type = 2). Refer to List 5.23 in the OpenRTB Spec 2.5 for more details. no
lat Latitude from −90.000 to +90.000, where negative is south. Truncated to three decimal places. Blank when not available. no
locale Language and country of the device. Example us_en signifies English as language and the United States as the country. no
lon Longitude from −180.000 to +180.000, where negative is west. Truncated to three decimal places. Blank when not available. no
metro Zip code of the device. Based on the IP address & Maxmind database. no
region Region code using ISO-3166-2; two-letter state code if USA. Always derived from IP address, never a reverse geocode from lat / lon. no
type Source of location data; recommended when passing lat / lon. Refer to List 5.20 in the OpenRTB Spec 2.5 for more details. no
zip (optional) Zip code of the user. Always derived, never a reverse geocode from lat / lon. no

Impression Object

An AppLovin RTB bid request always carries a single impression (this differs from the OpenRTB schema). Each request has exactly one impression object (imp).

If the request includes a banner object in the impression object, the impression is eligible for HTML and MRAID ads. If the request includes a video object, the impression is eligible for VAST ads. The impression object may either include only a banner or video sub-object, or it may include both such objects.

Attribute Description Always Passed?
banner A Banner object (see Banner Object)–required if this impression is offered as a banner ad opportunity. only for banner impressions
bidfloor CPM minimum bid amount. Default currency is USD. no
displaymanager Will pass “applovin” when the SDK is present. no
displaymanagerserver AppLovin SDK version passed from the SDK, otherwise not passed. no
exp Advisory as to the number of seconds that may elapse between the auction and the actual impression. Fixed value of 14400 = 4 hours × 3600 seconds/hour. yes
ext Placeholder for exchange-specific extensions to OpenRTB. no
ext.skadn Support for Apple’s SKAdNetwork. See the OpenRTB SKAdNetwork extension for additional details. no
ext.skadn.skadnetids A subset of SKAdNetworkItem entries in the publisher app’s Info.plist that are relevant to the DSP. yes (if ext.skadn is passed)
ext.skadn.skadnetlist.max IABTL list containing the max entry ID of SKAdNetwork ID.  
ext.skadn.skadnetlist.excl Comma-separated list of integer IABTL registration IDs to be excluded from IABTL shared list.  
ext.skadn.sourceapp ID of publisher app in Apple’s App Store. Matches app.bundle. yes (if ext.skadn is passed)
ext.skadn.version Version of SKAdNetwork supported. Always "2.0" or higher. Dependent on both the OS version and the SDK version.

With the release of SKAdNetwork 2.1, this field is deprecated in favor of BidRequest.imp.ext.skadn.versions to support an array of version numbers.

yes (if ext.skadn is passed)
ext.skadn.versions Array of strings containing the supported SKAdNetwork versions. Always "2.0" or higher. Dependent on both the OS version and the SDK version. yes (if ext.skadn is passed)
ext.skadnetids IDs associated with Advanced Bidders only. no
id A unique identifier for the impression within the bid request. Typically the value starts with 1, then increments of up to n for n impressions. yes
instl Indicates if impression is offered as an interstitial opportunity. Set to 1 for full screen (interstitial), or 0 if interstitial is not available. yes
metric An array of Metric objects (see Metric Object). yes
native A Native object (see Native Object)—required if this impression is offered as a native ad opportunity. only for native impressions
rwdd Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. yes
secure Flag that indicates if the impression requires secure HTTPS URL creative assets and markup, where 0 = Non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed. For iOS auctions, this will always be 1 = secure. yes
tagid Identifier for specific ad placement or ad tag that was used to initiate the auction. For SDK bidders, the network placement ID for this impression. yes
video A Video object (see Video Object)—required if this impression is offered as a video ad opportunity. only for video impressions

Metric Object

Attribute Type Description
type string

Type of metric being presented using exchange-curated string names. Session duration (session_duration) is the total time a user has spent in a specific app, in seconds.

Session depth (session_depth) is the total number of ads a user has seen in a given app session. A session ends after a user has closed the app. Both session depth and session depth per ad format will be present in the bid request.

The following represent the total number of ads per format a user has seen in the app session:

  • session_depth_banner
  • session_depth_full
  • session_depth_medium_rectangle
  • session_depth_native
  • session_depth_rewarded
value float

Number representing the value of the metric. Not present for Viewability type.

Session Depth: Set to 0.0 if the user has not yet seen an ad within their current app session, or if the user has been inactive for 30 minutes.

vendor string

Source of the value using exchange-curated string names. If the exchange itself is the source (as opposed to a third party), EXCHANGE is always used unless specified otherwise.

Viewability: Set to ias for Integral Ad Science (IAS); set to moat for Moat. Dependent on the partners that are supported by the publisher. If only one is supported, only one will be passed. If both are supported, both will be passed. Does not apply to Open Measurement Viewability.

Video Object

Attribute Description Always Passed?
api List of supported API frameworks for this impression. See OpenRTB Spec 2.5 Table 5.6 for details. If an API is not explicitly listed, it is assumed not to be supported. no
battr Blocked creative attributes. See OpenRTB Spec 2.5 Table 5.3 for details. yes
companiontype Supported VAST ad companion types. See OpenRTB Spec 2.5 Table 5.14 for details. Some inventory supports all companion types and others static only. yes
ext.videotype "rewarded" if it’s a rewarded request no
h Height of the player in pixels. yes
linearity Indicates if the impression must be linear. This is set to 1 for all requests. yes
maxbitrate Maximum bitrate in Kbps. yes
maxduration Maximum video ad duration in seconds. yes
mimes Content MIME types supported. video/mp4 is supported. yes
minbitrate Minimum bitrate in Kbps. yes
minduration Minimum video ad duration in seconds. yes
placement Placement type for the impression. See OpenRTB Spec 2.5 Table 5.9 for details. yes
playbackmethod Allowed playback methods. If none specified, assume all are allowed. See OpenRTB Spec 2.5 Table 5.10 for details. yes
pos Ad position on screen. See OpenRTB Spec 2.5 Table 5.4 for details. no
protocols Array of supported video bid response protocols. VAST 2, VAST 3, and VAST 4 are supported. Protocols will reflect what the specific inventory source supports as some inventory only supports 2.0, others both 2.0/3.0. See OpenRTB Spec 2.5 Table 5.8 for details. yes
skipafter Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable yes
skipmin Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. yes
startdelay Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. See OpenRTB Spec 2.5 Table 5.12 for details. yes
w Width of the player in pixels. yes
Attribute Description Always Passed?
api List of supported API frameworks for this impression. See OpenRTB Spec 2.5 Table 5.6 for details. If an API is not explicitly listed, it is assumed not to be supported. no
battr Blocked creative attributes for banner. See OpenRTB Spec 2.5 Table 5.3 for details. yes
btype An array of integers indicating blocked types of banners. See OpenRTB Spec 2.5 Table 5.2 for details. yes
ext.bannertype "rewarded" if it’s a rewarded request no
format Array of format objects representing the banner sizes permitted. Height (h) and width (w) available to pass. If none are specified, then AppLovin recommends that you use the Bidrequest.imp.banner.h and Bidrequest.imp.w attributes. no
h Height of the impression in pixels. yes
id A unique identifier for this object. Values usually start at 1 and increase with each object; should be unique within an impression. no
pos Ad position on screen. See OpenRTB Spec 2.5 Table 5.4 for details. AppLovin RTB will always pass 1 = Above the Fold. yes
w Width of the impression in pixels. yes

Native Object

AppLovin native ads use OpenRTB Dynamic Native Ads API Specification Version 1.2. The impression object contains the native object. The native object contains the request field with the JSON string representation of the native request. AppLovin does not support video assets.

Attribute Description Always Passed?
api List of supported API frameworks for this impression. See OpenRTB Spec 2.5 Table 5.6 for details. If an API is not explicitly listed, it is assumed not to be supported. no
battr Blocked creative attributes for the native ad. See OpenRTB Spec 2.5 Table 5.3 for details. yes
eventtrackers Array of tracking objects to run with the ad, in response to the declared supported methods in the request. Replaces imptrackers and jstracker, which are to be deprecated. See OpenRTB Spec 1.2 section 4.7: Event Trackers Request Object for details. no
request Request payload complying with the Native Ad Specification. Note that this is a string. yes
request.assets An array of Asset Objects. Any bid must comply with the array of elements expressed by the Exchange. yes
request.assets[n].data Data object for ratings, prices, etc. See Data Object definition below. yes
request.assets[n].id Unique asset ID, assigned by exchange. yes
request.assets[n].img.hmin The minimum requested height of the image, in pixels. Use this option for any rescaling of images by the client. Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement. Set for icon image with a value of 80—require 1:1 aspect ratio. Set for main image with a value of 417—require 1.91:1 aspect ratio (1200×627, 1200×628, and 800×418 recommended). no
request.assets[n].img.type Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. See OpenRTB Native spec 1.2 Table 7.4 and 7.5 for details. yes
request.assets[n].img.wmin The minimum requested width of the image, in pixels. Use this option for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement. Set for icon image with a value of 80—require 1:1 aspect ratio. Set for main image with a value of 800—require 1.91:1 aspect ratio (1200×627, 1200×628, and 800×418 recommended). no
request.assets[n].required Set to 1 if asset is required (exchange will not accept a bid without it). yes
request.context The context in which the ad appears; set to 1501. yes
request.privacy Set to 1 when the native ad supports buyer-specific privacy notice. Field is absent when the native ad doesn’t support custom privacy links or if support is unknown. no
request.seq (see the layout types). 0 for the first ad, 1 for the second ad, and so on. This is not the sequence number of the content in the stream. no
ver Version of the Native Ad Specification to which the request complies; set to 1.2. yes

Bid Response

Size

The maximum size of the bid response is 4KB.

No Bids

To communicate a no-bid response, pass an empty response with a status code of 204.

Win/Loss/Billing Notifications

AppLovin RTB calls the win, loss, and billing notice URLs that the requester supplies in the request’s nurl, lurl, and burl fields respectively. AppLovin RTB calls the win URL when the auction completes and AppLovin sends the ad to the device. It calls the loss URL either during the auction, if the associated ad fails to load properly, or after a different winning ad loads. It calls the billing URL when the device renders the ad, that is, when the video starts playing, or, for graphic ads, when the device displays the ad.

The requester may embed macros into the specification of these notification URLs. AppLovin RTB will substitute appropriate values for those macros in the URL before AppLovin RTB requests the URL. The following list shows the macros that the requester may embed in these URLs:

Macro Description
These macros are case-sensitive; specify them in ALL CAPS. Enclose these macros in ${…} (e.g. ${AUCTION_ID}).
AUCTION_BID_ID ID of the bid, from the BidResponse.bidid attribute.
AUCTION_ID ID of the bid request, from the BidRequest.id attribute.
AUCTION_LOSS Loss reason code, as found in Table 5.25 of the OpenRTB 2.5 spec. Is only sent on lurl. Note that loss code “103 Lost to a Bid for a PMP Deal” will be used when the impression is won by a Direct Sold campaign at a higher priority.
AUCTION_MINIMUM_BID_TO_WIN Second highest bid price. If there is no winner, floor price is sent. Is only sent on nurl. Value passed is 0 when there is only one bid: the winning bid.
AUCTION_PRICE The auction clearing price. Uses the same currency and units as the bid. May be up to six decimals.

Example Win Bid URL with Macros

https://example.com/endpoint/auction=${AUCTION_ID}&price=${AUCTION_PRICE}

Ad Markup Standard

DSP bidders must include ad markup in the bid response. AppLovin RTB does not support returning the ad markup in response to the win notice.

Your ad markup must comply with AppLovin’s RTB ad markup standard. AppLovin’s RTB servers check the ad markup’s compliance as soon as they receive the bid, and then they perform the following sanity checks on the ad markup:

  • Ad markup is properly escaped.
  • Ad markup is URL-encoded, except for VAST ads.
  • HTML of the ad markup is a snippet.
  • When you bid with a rich media ad, put the content of the node in a CDATA construct. CDATA in XML requires no encoding whatsoever. However if you pass an XML document in a JSON-context, you must apply JSON syntax and escaping rules, as follows:
    • All double quotes are escaped as \".
    • Apostrophes are not escaped.
    • The XML doc is stripped of all tab and newline characters. (The Example VAST Ad Markup below is formatted for easy readability. Do not send extra whitespace in your actual ad markup.)

To verify that an ad markup snippet is valid JSON content (along with its CDATA), you can pass that snippet into the on-line JSONLint validator.

SDK bidders are not required to pass ad markup because all creatives should be rendered via your SDK. SDK bidders may use the admarkup field to pass custom data, which can be configured to be returned to your SDK at load time via the adapters.

Bid Response Components

There are three components to the bid response:

bidresponse
top-level object
seatbid
collection of bids made by the bidder on behalf of a specific seat
bid
an offer to buy a specific impression under certain business terms

Bid Response Object

Attribute Type Description Required?
bidid string Bidder generated response ID to assist with logging/tracking. no
cur string Currently only accepts, and defaults to, "USD". no
id string ID of the bid request to which this is a response (that is, it must match bidrequest.id). yes
nbr integer Reason for not bidding. Refer to List 5.24 of the OpenRTB 2.5 spec. recommended
seatbid object array Array of seatbid objects; one or more are required if a bid is to be made. yes

Seatbid Object

Attribute Type Description Required?
bid object array Array of bid objects; one or more are required if a bid is to be made. yes
seat string ID of the bidder seat on whose behalf this bid is made. A bid response may contain bids from multiple “seats” or contain multiple bids from the same seat. Must be an alphanumeric string, maximum 40 characters, ideally minimum 8 characters. Not currently supported. no

Bid Object

Attribute Type Description Required?
adid string ID of a preloaded ad to be served if the bid wins. no
adm string The main means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros may be included. Refer to supported macros. For native ad format adm_native is supported. yes
adomain string array This field contains an array of advertiser domain names. AppLovin RTB uses only the first domain in the array.

Advertiser domains must match the top-level domain name for the advertiser landing page, not the full landing page URL. For app store landing pages, adomain should match the app owner’s top-level domain name, not the full app store URL.

The value of adomain must not contain “http://”, “https://”, or any “/” (slash) characters.

Example: yourapp.com (but not yourapp.com/something or https://yourapp.com).

yes
api integer See OpenRTB Spec 2.5 Table 5.6 for details. no
apis integer array List of supported API frameworks for this impression. One of the following:
1 VPAID 1.0
2 VPAID 2.0
3 MRAID-1
4 ORMMA
5 MRAID-2
6 MRAID-3
7 OMID-1
 
attr integer array Required when applicable, creative attributes, an array of values taken from this list:
1 Audio Ad (Auto-Play)
2 Audio Ad (User Initiated)
3 Expandable (Automatic)
4 Expandable (User Initiated–Click)
5 Expandable (User Initiated–Rollover)
6 In-Banner Video Ad (Auto-Play)
7 In-Banner Video Ad (User Initiated)
8 Pop (e.g. Over, Under, or Upon Exit)
9 Provocative or Suggestive Imagery
10 Shaky, Flashing, Flickering, Extreme Animation, Smileys
11 Surveys
12 Text Only
13 User Interactive (e.g. Embedded Games)
14 Windows Dialog or Alert Style
15 Has Audio On/Off Button
16 Ad Provides Skip Button (e.g. VPAID-rendered skip button on pre-roll video)
17 Adobe Flash
When present, this must be accurate and reflect the actual creative, otherwise it is a policy violation. This field is not required for serving VAST video but is required for serving HTML or MRAID in-banner video.
recommended
bundle string This field contains the advertiser’s application iTunes ID or Android package name. If this is not an application install ad, leave this field blank. Do not pass the publisher’s application bundle or AppLovin RTB will reject the response.

Examples: com.example.app on Android, 628677149 on iOS.

required if ext.skadn is present; recommended in all cases
burl string Billing notice URL called by the exchange when a winning bid becomes billable. DSPs must use burl for impression and spend tracking. AppLovin will only investigate discrepancies when burl is used for tracking. yes
cat string array IAB content categories of the creative. Refer to section 5.1 of the OpenRTB 2.5 spec. yes
cid string Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. recommended
crid string This field uniquely identifies a creative for a campaign. Do not assign a new creative ID to the same creative just to indicate that the creative is appearing in a new impression. yes
dealid string Reference to the deal.id from the bid request if this bid pertains to an inventory package. Do not pass unless bidding against an inventory package. yes, for inventory packages
ext object Placeholder for bidder-specific extensions to OpenRTB. no
ext.crtype string This field describes the type of ad you are serving. Valid values are:
  • HTML
  • MRAID 1.0
  • MRAID 2.0
  • MRAID 3.0
  • native
  • VAST 2.0
  • VAST 3.0
  • VAST 4.0
AppLovin can hardcode the crtype for you if you buy only one crtype. Contact your AppLovin account manager if you would like to do this. Passing crtype in bid.crtype is also supported.
recommended
ext.clicktrackers string array Click tracking URLs (first- and third-party) to be consistently tracked when AppLovin records the click event. This does not apply to native. yes, if running HTML ads + SKAD (SKAdNetwork)
ext.duration integer Video duration, in seconds. yes, for CTV inventory
ext.imptrackers string array Impression tracking URL to be used by third-party tracking needs. This does not apply for native. See native object eventtrackers. no
ext.skadn object Parameters required to support Apple’s SKAdNetwork attribution API, via loadProduct(). no
ext.skadn.campaign string Campaign ID (2.0–3.0) or Source ID (4.0+). This should be an integer between 1 and 100 for SKAdNetwork versions 2.0–3.0, or between 0 and 9999 for versions 4.0+, expressed as a string. if ext.skadn is present
ext.skadn.fidelities object array Supports multiple fidelity types introduced in SKAdNetwork v2.2. if ext.skadn is present
….fidelities[n].fidelity integer The fidelity-type of the attribution to track. if ext.skadn is present
….fidelities[n].nonce string An ID unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements. if ext.skadn is present
….fidelities[n].signature string SKAdNetwork signature as specified by Apple. if ext.skadn is present
….fidelities[n].timestamp string Unix time in milliseconds string used at the time of signature. if ext.skadn is present
ext.skadn.itunesitem string ID of advertiser’s app in Apple’s app store. Should match BidResponse.seatbid.bid.bundle. if ext.skadn is present
ext.skadn.network string Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request. if ext.skadn is present
ext.skadn.nonce string An ID unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements.

With the release of SKAdNetwork v2.2, this field is deprecated in favor of BidResponse.seatbid.bid.ext.skadn.fidelities.nonce to support multiple fidelity-types.

if ext.skadn is present
ext.skadn.productpage string Custom Product Page ID (available as of SDK 11.1.1) no
ext.skadn.signature string SKAdNetwork signature as specified by Apple.

With the release of SKAdNetwork 2.2, this field is deprecated in favor of BidResponse.seatbid.bid.ext.skadn.fidelities.signature to support multiple fidelity-types.

if ext.skadn is present
ext.skadn.skoverlay object Parameters to control a potential SKOverlay (available as of SDK 10.0.0). The overlay can be triggered (with delay, or 0 for no delay) after video starts, companion ad renders, or user dismisses the overlay but the ad remains open.

AppLovin does not track clicks on SKOverlay, as Apple does not provide a click callback.

no
….skoverlay.position integer Position of the overlay. 0 = bottom, 1 = bottomRaised. Defaults to 0. no
….skoverlay.dismissable integer Whether or not the user can dismiss the overlay (1 means it can be dismissed, 0 means it is static on the screen). Defaults to 1. no
….skoverlay.video_delay integer Number of seconds after the video starts to show the overlay. Keep this unset (null) to not trigger based on video start. no
….skoverlay.companion_delay integer Number of seconds after the companion ad renders to show the overlay. Keep this unset (null) to not trigger based on companion ad render. if ext.skadn.skoverlay is present
….skoverlay.sk_dismiss_delay integer Number of seconds after the presented StoreKit screen is dismissed before showing the overlay. Keep this unset (null) to not trigger based on StoreKit dismiss (available as of SDK 11.3.4). if ext.skadn.skoverlay is present
ext.skadn.sourceapp string ID of publisher’s app in Apple’s app store. Should match BidRequest.imp.ext.skad.sourceapp. if ext.skadn is present
ext.skadn.timestamp string Unix time in milliseconds string used at the time of signature.

With the release of SKAdNetwork 2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities.timestamp to support multiple fidelity-types.

if ext.skadn is present
ext.skadn.version string Version of SKAdNetwork desired. Must be 2.0 or above. if ext.skadn is present
ext.vendor string array Name of viewability vendor(s) that will be measuring viewability for the ad that is shown. You should only declare viewability vendors in the bid response when you are collecting viewability measurement for an impression. Set to "ias" for Integral Ad Science (IAS). Set to "moat" for Moat Buyers are required to respond with the vendor in the bid response when they are returning a display campaign for viewability. Does not apply to Open Measurement Viewability. for campaigns that measure viewability
h integer Height of the creative in density-independent pixels. recommended
id string Bidder generated bid ID to assist with logging/tracking. yes
impid string ID of the Impression object in the related bid request. yes
lurl string Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Refer to supported macros. no
nurl string Win notice URL called by the exchange if the bid wins the impression opportunity. recommended
price float Bid price expressed as CPM, although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (for example, BigDecimal in Java). yes
protocol integer Video response protocol of the markup if applicable. See OpenRTB Spec 2.5 Table 5.8 for details. no
w integer Width of the creative in density-independent pixels. recommended

Tracking Fields

The following table shows the tracking fields available to Demand Side Platforms, and their recommended uses.

Impressions and spend tracking must be done through the bid response field burl. AppLovin will only investigate discrepancies when burl is used for tracking.

Tracker Method Recommended Use
bidresponse.bid.burl Fired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
X-Device-IP
Actual user device IP address
X-Device-User-Agent
Actual user device UA
Impression and spend tracking for the buyer (DSP)
bidresponse.bid.ext.imptrackers Fired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
X-Device-IP
Actual user device IP address
X-Device-User-Agent
Actual user device UA
Impression tracking by partners
bidresponse.bid.adm
  • HTML Fired client-side
  • VAST <ImpressionTracker> node Fired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
    X-Device-IP
    Actual user device IP address
    X-Device-User-Agent
    Actual user device UA
  • HTML: Invalid Traffic (IVT) tracking
  • VAST: Impression tracking by partners
bidresponse.bid.adm.native.eventtrackers Fired client-side
  • Invalid Traffic (IVT) tracking
  • Open Measurement SDK (OMSDK)
  • Impression tracking by partners
Supports img and js tags as defined in “methods” in 7.7 Event Tracking Methods Table of Open RTB 1.2 Native Ads Spec.

DSPs are encouraged to use native.eventtrackers rather than native.imptrackers or native.jstracker as those fields are pending deprection by IAB (being deprecated in favor of eventtrackers).

bidresponse.bid.adm.native.imptrackers Fired client-side (being deprecated in favor of eventtrackers) Invalid Traffic (IVT) tracking
bidresponse.bid.adm.native.jstracker Fired client-side (being deprecated in favor of eventtrackers) Open Measurement SDK (OMSDK)

Creative Types

The following details on creative types apply to DSP bidders in the AppLovin Exchange.

When you introduce a new creative format, AppLovin highly encourages that you test with the AppLovin DSP Sample App before you go live.

SDK bidders must handle the rendering of creatives via their own SDK and should reach out to their AppLovin contact should they have any questions.

VAST Support

VAST videos auto-play on Android and iOS. AppLovin supports only Linear videos. Videos should be at least 5 seconds long and at most 30 seconds long. Video file sizes should be below 4MB (for optimal playback, AppLovin recommends video files to be smaller than 2MB). AppLovin aspect-fits the video in the middle of the screen depending on device size.

The adm (or ad markup field) must contain the entire VAST 2.0 XML payload, VAST 3.0 XML payload, or VAST 4.0 XML payload. AppLovin does not support URL-encoded VAST tags. Embed VAST in bid.adm.

AppLovin supports VAST Wrapper only on newer SDKs: Android 7.0.0+ (for Interstitial only; Wrapper tags not supported for Rewarded) or iOS 4.0.0+ (Interstitial and Rewarded).

Impression Tracking

AppLovin fires tags on the server side that you send through the <impression> node. You can send more than one such node.

Click Tracking

AppLovin fires the tag on the client side that you send through the <ClickTracking> node. If you use a deep-link, you must include it in the <ClickThrough> node.

If you use a deep-link in an iOS ad, the ext.skadn object must be null. Otherwise the App Store will be opened within the ad and the <ClickThrough> node will be dismissed.

AppLovin supports quartile tracking only on newer SDKs: Android 7.0.0+ or iOS 4.0.0+.

Companion Ads

AppLovin RTB expects a full-screen companion ad in the response for VAST ads. The request specifies the phone screen dimensions. The AppLovin SDK aspect-fits the ad in the middle of the screen. Since these are video end cards, use something in the ~1.33 aspect ratio range (e.g. 1024×768 for landscape) and high quality images for best results with companion ads.

AppLovin supports only <HTMLResource> and <StaticResource>. Support for <HTMLResource> as a companion ad is off by default.

Example VAST Ad Markup

{
  "adm": "<VAST version=\"2.0\">
    <Ad id=\"applovin-video\">
      <InLine>
        <AdSystem version=\"AppLovin\">AppLovin Ad Server</AdSystem>
        <AdTitle><![CDATA[AppLovin Video]]></AdTitle>
        <Description><![CDATA[AppLovin Video]]></Description>
        <Impression id=\"AL_Imp\" />
        <Creatives>
          <Creative sequence=\"1\" id=\"1\">
            <Linear>
              <Duration>00:00:13</Duration>
              <VideoClicks>
                <ClickThrough id=\"AL_Click\"><![CDATA[https://rtb.applovin.com/redirect?clcode=3!1563.1466706706!FgcnDB8CXKyVimq2aZHmpR2JxNmwsN1NMK7UlK6FqhOI54WxpITXiYcxUEVgXRIwedrcfVmD_DpD3lfBLqzpw5qF7sPXmXQ_kY1NLKQ2kdQn4cwctkm--RBq1Cmz5mX8RJRytc-G3KeJ9usTmgmXTSFtLvHGSGHIM7Pwfq_KiEAQiKweR20lp_iyQXVNwiUJmpFFoQpAm9bNU5JegcmPfIIBnesZKk5pmdJDpUEnjlFdNAqRCzci_qO-f6RtTdYEvJBqnh9usSgEdxnfLh-hHpNx5CovcfTejFfF94CTaTV_K6wEHXQOjZdT-yfdeydAQEkl3bUxiT8cXrEuCu73WHFVOoYwoLJLLAipuLCNCkj9DSvZ6JTnoQkPRlpBjSJQmmYXNv2HDKXYKSgIA-g-wRaTuRZ0lMi4OHNBK_N4ClACeg2TOFYTp3cHWnh6gEr-ZfWQ4FUzgGCLQRXm0Ez7wjCRM0vfoVsdVEZrctobQI7_im9tT4UmTjNgxP7dKlLHRwhl68fBqGUMobFSsohmuucakp5BXlSPyQIh91MoTOOsbR2UTMZXjFholy7qDgDxNxKzaQk0AFX6Vf0w**&did=104934ef84eee135bb&eventid=7d2a138bf9102f05dcbf9540b5f5dd2a317cc&ssl=1]]></ClickThrough>
              </VideoClicks>
              <MediaFiles>
                <MediaFile delivery=\"progressive\" bitrate=\"932\" width=\"570\" height=\"320\" type=\"video/mp4\"><![CDATA[https://vid.applovin.com/468779_570x320.mp4]]></MediaFile>
              </MediaFiles>
            </Linear>
          </Creative>
          <Creative sequence=\"1\" id=\"1\">
            <CompanionAds>
              <Companion width=\"1024\" height=\"768\">
                <StaticResource creativeType=\"image/gif\"><![CDATA[https://img.applovin.com/1461768_1024x768.gif]]></StaticResource>
                <CompanionClickThrough><![CDATA[https://rtb.applovin.com/redirect?clcode=3!1563.1466706806!FgcnDB8CXKHpfIyVimq2aZHmpR2JxNmwsN1NMK7UlK6FqhOI54WxpITXiYcxUEVgXRIwedrcfVmD_DpD3lfBLqzpw5qF7sPXmXQ_kY1NLKQ2kdQn4cwctkm--RBq1Cmz5mX8RJRytc-G3KeJ9usTmgmXTSFtLvHGSGHIM7Pwfq_KiEAQiKweR20lp_iyQXVNwiUJmpFFoQpAm9bNU5JegcmPfIIBnesZKk5pmdJDpUEnjlFdNAqRCzci_qO-f6RtTdYEvJBqnh9usSgEdxnfLh-hHpNx5CovcfTejFfF94CTaTV_K6wEHXQOjZdT-yfdeydAQEkl3bUxiT8cXrEuCu73WHFVOoYwoLJLLAipuLCNCkj9DSvZ6JTnoQkPRlpBjSJQmmYXNv2HDKXYKSgIA-g-wRaTuRZ0lMi4OHNBK_N4ClACeg2TOFYTp3cHWnh6gEr-ZfWQ4FUzgGCLQRXm0Ez7wjCRM0vfoVsdVEZrctobQI7_im9tT4UmTjNgxP7dKlLHRwhl68fBqGUMobFSsohmuucakp5BXlSPyQIh91MoTOOsbR2UTMZXjFholy7qDgDxNxyGKzaQk0AFX6Vf0w**&did=104924ef84eee135bb&eventid=7d82abf9102f05dcbf9540b5f5dd2a317cc&ssl=1]]></CompanionClickThrough>
              </Companion>
            </CompanionAds>
          </Creative>
        </Creatives>
        <Extensions>
        </Extensions>
      </InLine>
    </Ad>
  </VAST>"
}

MRAID Support

MRAID ads must include a loading indicator to signal that the ad is loading. There is no limit on ad duration for regular MRAID ads, but rewarded MRAID ads have a maximum of 30s. AppLovin supports mraid.open only for click trackers.

Rewarded MRAID placements (playable ads) are off by default. If you are interested in these, please contact your AppLovin point of contact.

Close Button

Remove the close button if any. AppLovin supplies the close button on all MRAID ads.

HTML Support

AppLovin RTB centers all HTML ads. The resulting ad position depends on the ad size and the screen size. AppLovin supplies the close button.

Native Support

AppLovin native ads use OpenRTB Dynamic Native Ads API Specification Version 1.2.

The impression object contains the native object. The native object contains the request field with the JSON string representation of the native request.

Native Request Information

Field Description
context The context in which the ad appears; currently not used and always set to 1501.
plcmtcnt The placement count (AppLovin requests only one placement per request).
plcmttype The design/format/layout of the ad unit being offered. 1 means in the feed of the content; 2 means in the atomic unit of the content.
ver The version of the Native Ad Specification to which the request complies; set to 1.2.

Native Request Assets

ID Field Type Description
1 (required) title N/A Title of the native ad. Maximum length is 140 characters. Always passes Bidrequest.imp.native.request.assets.len, the maximum length of the text in the title element.
2 (required) img 3 Main image of the native creative. Minimum required size is 627×627. Recommended size is 1200×627.
3 (optional) img 1 Icon image of the native creative. Minimum required size is 50×50.
4 (optional) data 2 Descriptive text associated with the text product or service being advertised. Maximum length is 140 characters.

Bidrequest.imp.native.request.assets.data contains .type and .len objects. The type contains the Type ID of the element supported by the publisher. The len is the maximum length of the text in the element’s response.

5 (required) data 12 CTA description—descriptive text describing a “call to action” button for the destination URL. Maximum length is 15 characters.

Bidrequest.imp.native.request.assets.data contains .type and .len objects. The type contains the Type ID of the element supported by the publisher. The len is the maximum length of the text in the element’s response.

6 (optional) data 3 Rating of the product being offered to the user. For example, an app’s rating in an app store on a 0–5 scale.
8 (optional) data 1 “Sponsored By” message in which the response should contain the brand name of the sponsor. Maximum length is 25 characters.

Native Response Information

Native response must have native.link.url with the destination link URL.

The AppLovin SDK does not yet support native video.

CTV Support

AppLovin RTB supports Connected TV (CTV) inventory. The following will help with a successful integration:

  • CTV requests support video only, so there is no banner object under the imp object.
  • VAST is the only supported format for Connected TV inventory. AppLovin does not support MRAID or VPAID.
  • Only the mp4 video MIME type is supported.
  • seatbid.bid.ext.duration is mandatory.

For VAST InLine:

Ad Caching

The AppLovin SDK caches certain ads to improve ad display responsiveness. Cached ads are shown only in the same session. The SDK caches ads for up to four hours, but normally the period between cache and show is only a few minutes.

Video
AppLovin caches only inline video ads. For optimal responsiveness, the maximum video file size allowed is 4MB. Try to keep video file sizes below 2MB.
MRAID
AppLovin does not cache MRAID ads. While AppLovin does not have a size limit, keep your creative assets in your MRAID markup as lean as possible to ensure your ads are responsive when the publisher attempts to render them. All MRAID ads must include a loading indicator to signal when the ad is loading. The AppLovin close button appears after five seconds, regardless of loading status.

Example Bid Request

{
  "app": {
    "bundle": "com.example.game",
    "cat": ["IAB9-30"],
    "id": "188e1f4c72744d3da3134a25",
    "name": "Example Game",
    "publisher": {
      "id": "41c8cd761e099946e85842c11debfb4d"
    },
    "storeurl": "https://play.google.com/store/apps/details?id=com.example.game"
  },
  "at": 2,
  "bcat": ["IAB8-5","IAB8-18","IAB11-4","IAB25","IAB26"],
  "device": {
    "carrier": "telekomde",
    "connectiontype": 3,
    "devicetype": 4,
    "dnt": 0,
    "geo": {
      "city": "Barrington",
      "country": "USA",
      "metro": "",
      "type": 2,
      "zip": ""
    },
    "h": 1280,
    "hwv": "hllte",
    "ifa": "e1020eb8-fc74-454d-b420-a9763d8bc556",
    "ip": "203.0.113.12",
    "js": 1,
    "language": "de",
    "lmt": 0,
    "make": "samsung",
    "model": "SM-N7505",
    "os": "Android",
    "osv": "5.1.1",
    "ua": "Mozilla/5.0 (Linux; Android 4.3; SM-N7505 Build/JSS15J) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.89 Mobile Safari/537.36",
    "w": 720
  },
  "id": "94dedeadbeefc4b8fcba406639bbf15912766bdc",
  "imp": [
    {
      "banner": {
        "api": [
          3,
          5
        ],
        "battr": [
          1,
          2,
          5,
          8,
          9,
         14,
         17
        ],
        "btype": [
          1,
          4
        ],
        "h": 480,
        "pos": 1,
        "w": 320
      },
     "displaymanager": "applovin",
     "displaymanagerver": "6.1.4",
     "id": "1",
     "instl": 1,
     "secure": 0,
     "tagid": "0652dbc39a23edfd",
     "video": {
        "battr": [
          1,
          2,
          3,
          7,
          8,
          9,
         14,
         13
        ],
        "companiontype": [
          1,
          2,
          3
        ],
        "h": 480,
        "linearity": 1,
        "mimes": [
          "video/mp4"
        ],
        "protocols": [
          2,
          3
        ],
        "w": 320
      }
    }
  ]
}

Example Native Bid Request

{
  "app": {
    "bundle": "com.example.game",
    "cat": [
      "IAB24"
    ],
    "id": "81a292321de8ed119cb833e0a80c4231",
    "name": "Example Game",
    "publisher": {
      "id": "41c8cd761e099946e85842c11debfb4d"
    },
    "storeurl": "https://play.google.com/store/apps/details?id=com.example.game"
  },
  "at": 2,
  "badv": [
  ],
  "device": {
    "carrier": "verizon",
    "connectiontype": 2,
    "devicetype": 4,
    "dnt": 0,
    "geo": {
      "city": "Redwood City",
      "country": "USA",
      "metro": "",
      "type": 2
    },
    "h": 0,
    "hwv": "",
    "ifa": "12341234-1234-1234-1234-123412341234",
    "ip": "255.255.255.255",
    "ipv6": "2a00:79e1:abc:6b01:d516:20e2:582d:339a",
    "js": 1,
    "language": "en",
    "lmt": 0,
    "make": "",
    "model": "",
    "os": "Android",
    "osv": "8.0.0",
    "ua": "Mozilla/5.0 (Linux; Android 8.0.0; en_US; Moto Z (2) Build/ODXS27.000-00-00) AppleWebKit/000.00 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Mobile Safari/000.00",
    "w": 0
  },
  "id": "d628d2709c061c14ea4a2e17a52da1778534d1f5",
  "imp": [
    {
      "displaymanager": "applovin",
      "displaymanagerver": "6.0.0",
      "ext": { },
      "id": "1",
      "native": {
        "api": [],
        "battr": [
          1,
          2,
          5,
          8,
          9,
         14,
         17,
          3,
          4,
         13
        ],
        "request": "{"native":{"assets":[{"id":1,"required":1,"title":{"len":140}},{"id":2,"img":{"hmin":800,"type":3,"wmin":417},"required":1},{"id":3,"img":{"hmin":50,"type":1,"wmin":50},"required":1},{"data":{"len":140,"type":2},"id":4,"required":0},{"data":{"len":15,"type":12},"id":5,"required":1},"context":1501,"plcmtcnt":1,"plcmttype":1,"ver":"1.2"}}",
        "ver": "1.2"
      },
      "secure": 0,
      "tagid": "5ba489fc7ec59a27:NOTIFYCLEAN"
    }
  ]
}

Example CTV Bid Request

{
  "id": "eb3ebe82eb5223c2525d46bd3bef213649466b0a",
  "at": 1,
  "bcat": [
    "IAB11-4",
    "IAB8-5",
    "test1",
    "IAB8-18",
    "IAB25-7",
    "IAB25-1",
    "IAB25-5",
    "IAB25-2",
    "IAB25-3",
    "IAB26-1",
    "IAB25-4",
    "IAB26-4",
    "IAB26-2",
    "IAB26-3",
    "IAB25-6",
    "test2"
  ],
  "tmax": 1000,
  "badv": [
    "test2",
    "test1"
  ],
  "app": {
    "name": "APPINT",
    "bundle": "com.applovin.appint",
    "cat": [],
    "id": "a9dad9c29f02533c9462db5555561e79",
    "publisher": {
      "id": "61310",
      "ext": {}
    },
    "content": {
      "contentrating": "TV-PG",
      "genre": "Documentary,Science",
      "episode": 2,
      "season": "7",
      "ext": {
        "channel": "AppLovin Test"
      }
    },
    "storeurl": "https://channelstore.roku.com/details/196460",
    "ext": {}
  },
  "device": {
    "ifa": "66dcd4a1-a0ed-b2b8-7e1a-3d2ea2ecc889",
    "ip": "204.14.60.221",
    "language": "en",
    "devicetype": 3,
    "js": 0,
    "geo": {
      "type": 2,
      "ipservice": 3,
      "lat": 42.2441,
      "lon": -75.2871,
      "long": -75.2871,
      "city": "Sidney Center",
      "country": "USA",
      "region": "ny",
      "dma": "502",
      "metro": "502",
      "zip": "13839",
      "ext": {
        "org": "DTC Cable",
        "isp": "DTC Cable"
      }
    },
    "ext": {},
    "make": "Roku",
    "model": "DVP",
    "os": "Roku OS",
    "dnt": 0,
    "lmt": 0
  },
  "imp": [
    {
      "id": "1",
      "displaymanager": "applovin",
      "instl": 0,
      "secure": 1,
      "tagid": "2f850a687d1acfdb:",
      "bidfloor": 22.58823529411765,
      "bidfloorcur": "USD",
      "exp": 14400,
      "video": {
        "w": 1920,
        "h": 1080,
        "battr": [
          1,
          2,
          5,
          8,
          9,
          14,
          17,
          3,
          4,
          13
        ],
        "mimes": [
          "video/mp4",
          "video/ogg",
          "video/webm"
        ],
        "placement": 1,
        "pos": 1,
        "minduration": 1,
        "maxduration": 120,
        "startdelay": -1,
        "minbitrate": 1,
        "maxbitrate": 280000,
        "linearity": 1,
        "sequence": 1,
        "protocols": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "podid": "pod_1",
        "podseq": 0,
        "slotinpod": 0,
        "ext": {
          "maxsequence": 1
        }
      },
      "rwdd": 0,
      "ext": {}
    }
  ],
  "user": {
    "ext": {
      "gdpr": 0
    },
    "id": "66dcd4a1-a0ed-b2b8-7e1a-3d2ea2ecc889"
  },
  "regs": {
    "coppa": 0,
    "ext": {
      "ccpa": 0,
      "gdpr": 0
    }
  },
  "source": {
    "ext": {
      "schain": {
        "ver": "1.0",
        "complete": 1,
        "nodes": [
          {
            "asi": "applovin.com",
            "sid": "61310",
            "rid": "eb3ebe82eb5223c2525d46bd3bef213649466b0a",
            "hp": 1
          }
        ]
      }
    }
  }
}

Example Bid Response

{
  "id": "5e1eb292d6b7ea9cf3da74ddb385996a62d3a6e9",
  "seatbid": [
    {
      "bid": [
        {
          "id": "8JxH4DHN4KMF21Vd",
          "impid": "1",
          "price": 15,
          "adid": "1093919",
          "adm": "<a href=\"https://click.url/click/8JxH4DHN4KMF21Vd?uid=05D02DC6-0132-4C2C-A879-79BB026BE3F8&partner=applovin&ts=2018-07-09T18-19-01Z&ad=1093919\"><img src=\"https://assets.dsp.io/ad_assets/files/320x50.png\" height=\"50\" width=\"320\" alt=\"\"/></a>",
          "adomain": [
            "advertiser.com"
          ],
          "bundle": "123123123",
          "iurl": "https://assets.dsp.io/ad_assets/files/320x50.png",
          "cid": "12345",
          "crid": "crid123",
          "cat": [
            "IAB22-2"
          ],
          "h": 50,
          "w": 320,
          "ext": {
            "crtype": "HTML",
            "imptrackers": [
                "https://example.dsp.events/win/8JxH4DHN4KMF21Vd?ts=2018-07-09T18-19-01Z&ad=1093919&uid=05D02DC6-0132-4C2C-A879-79BB026BE3F8&auction=${AUCTION_ID}&price=${AUCTION_PRICE}&partner=applovin"
            ]
          }
        }
      ]
    }
  ],
  "bidid": "8JxH4DHN4KMF21Vd",
  "cur": "USD"
}

Example Native Ad Response

{
  "bidid":"9aa2a2950894c95b9b02476a5ba5438dc6de8dc1",
  "cur":"USD",
  "id":"65de6af36e6fb32778afa94a996ec4c2b514145d",
  "seatbid":[
    {
      "bid":[
        {
          "adm":"{\"native\":{\"assets\":[{\"id\":100,\"title\":{\"text\":\"Test Ad\"}},{\"id\":200},{\"id\":300,\"img\":{\"h\":null,\"url\":\"https://assets.com/main_image.png_\",\"w\":null}},{\"id\":310,\"img\":{\"h\":80,\"url\":\"https://assets.com/icon_image.png\",\"w\":80}},{\"data\":{\"value\":\"Test Ad Subline\"},\"id\":420},{\"data\":{\"value\":\"Continue\"},\"id\":430},{\"data\":{\"value\":\"4.5\"},\"id\":410}],\"imptrackers\":[\"https://adserver.com/impression_tracker\"],\"link\":{\"url\":\"https://adserver.com/click_destination\"}}}\n",
          "adomain":[
            "somegame.com"
          ],
          "bundle":"com.game.example",
          "cat":[
            "IAB1"
          ],
          "crid":"74650.0!3ILDTypkALKe8xfw2WJLmxfNOftiOg2u3yeGIKEULAU*",
          "ext": {
            "crtype":"native"
          },
          "id": "1",
          "impid": "1",
          "iurl": "https://assets.com/preview.png",
          "price": 1.0
        }
      ],
      "seat":"A00000001"
    }
  ]
}

Changelog

Release Date Notes
Jul. 2023 Compressed/gzip oRTB required. Adhere to OpenRTB API Specification version 2.5 section 2.4: Data Encoding.
May 2023 Tracking URLs embedded in the VAST XML for video ads do not fire consistently for apps using Android SDK version 11.8.2 (released March 13, 2023) or 11.9.0 (released April 10, 2023). Issue is resolved as of SDK version 11.10.0 (released May, 21 2023).
Apr. 2023 Smart Throttling enabled for all DSP buyers.
Apr. 5, 2023 Include only those SKAdNetwork ID(s) in the imp[n].ext.skadn bid request object that are integrated into the app and that belong exclusively to the DSP that the request is being sent to.
Feb. 21, 2023 The imp.tagid bid request field is now unique to the ad unit. Prior to this, imp.tagid was not passed consistently, and a single value was used at the app/package level.
Jan. 2023 Add support for CTV
Sep. 30, 2022 Add X-Device-IP and X-Device-User-Agent headers to server-to-server impression callbacks.
  • X-Device-IP: Actual user device IP address
  • X-Device-User-Agent: Actual user device UA.
May 11, 2022 VAST Wrapper tags no longer supported for Android Rewarded.
Feb. 24, 2022 Add support for Native format as of AppLovin SDK iOS 11.1.2 / Android 11.1.3.
Dec. 31, 2021 Add support for passing IDFV in the device.ext.ifv field. Only passed when IDFA is not available. Currently passed for iOS only.