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) |
|
Banner object (HTML, MRAID, MREC) |
|
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
|
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:
|
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 |
pmp | A private marketplace object containing any private marketplace deals in effect for this impression. See IAB oRTB Section 3.2.11 for more details. | no |
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:
|
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 |
Banner 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 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 at this point.
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, 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 across DSPs. 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 for the advertiser landing page. For app store landing pages, adomain should match the app owner’s top-level domain and not the full app store URL.
Examples: advertiser.com or advertiser.jp or advertiser.fr. |
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:
|
|||||||||||||||||||||||||||||||||||
attr | integer array | Required when applicable, creative attributes, an array of values taken from this list:
|
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 a private marketplace direct deal.
Do not pass unless bidding against a private marketplace deal or inventory package. |
yes, for PMP | ||||||||||||||||||||||||||||||||||
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:
|
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 | ||||||||||||||||||||||||||||||||||
ext.skadn.fidelities[n].fidelity | integer | The fidelity-type of the attribution to track. | if ext.skadn is present | ||||||||||||||||||||||||||||||||||
ext.skadn.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 | ||||||||||||||||||||||||||||||||||
ext.skadn.fidelities[n].signature | string | SKAdNetwork signature as specified by Apple. | if ext.skadn is present | ||||||||||||||||||||||||||||||||||
ext.skadn.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 | ||||||||||||||||||||||||||||||||||
ext.skadn.skoverlay.position | integer | Position of the overlay. 0 = bottom, 1 = bottomRaised. Defaults to 0. | no | ||||||||||||||||||||||||||||||||||
ext.skadn.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 | ||||||||||||||||||||||||||||||||||
ext.skadn.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 | ||||||||||||||||||||||||||||||||||
ext.skadn.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 | ||||||||||||||||||||||||||||||||||
ext.skadn.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:
|
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:
|
Impression tracking by partners |
bidresponse.bid.adm |
|
|
bidresponse.bid.adm.native.eventtrackers | Fired client-side |
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.
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. |
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:
- The bitrate should fall between minbitrate and maxbitrate sent in the bid request.
- The width and height should be equal to imp.video.w and imp.video.h in the bid request.
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.
,
"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.
|
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. |