To communicate a no-bid response, pass an empty response with a status code of 204.
Win/Loss/Billing NotificationsCopy Link
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 substitutes 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:
These macros are case-sensitive; specify them in ALL CAPS.
Enclose these macros in ${…} (e.g. ${AUCTION_ID}).
Macro
Description
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. Only sent on lurl.
AUCTION_MINIMUM_BID_TO_WIN
Second highest bid price. 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.
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.
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.
an offer to buy a specific impression under certain business terms
Bid Response ObjectCopy Link
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 (this 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 ObjectCopy Link
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 ObjectCopy Link
Attribute
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)
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 adomainmust not contain “http://”, “https://”, or any “/” (slash) characters. Example: yourapp.com (but notyourapp.com/something or https://yourapp.com).
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)
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 only investigates 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)
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
VAST 4.1
VAST 4.2
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 objecteventtrackers.
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.
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. Note: With the release of SKAdNetwork v2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].nonce which supports multiple fidelity-types.
if ext.skadn is present
ext.skadn.productpage (string)
Custom Product Page ID.
no
ext.skadn.signature (string)
SKAdNetwork signature as specified by Apple. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].signature which supports multiple fidelity-types.
if ext.skadn is present
ext.skadn.skoverlay (object)
Parameters to control a potential SKOverlay. 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. Note: 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. Set this to -1 to not trigger based on video start.
if ext.skadn.skoverlay is present
….skoverlay.companion_delay (integer)
Number of seconds after the companion ad renders to show the overlay. Set this to -1 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. Set this to -1 to not trigger based on StoreKit dismiss.
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. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].timestamp which supports 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 measure viewability for the ad that is shown. You should only declare viewability vendors in the bid response when you collect 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 return 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.
Loss notice URL called by the exchange when a bid is known to be 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 FieldsCopy Link
The following table shows the tracking fields available to demand-side platforms, and their recommended uses.
bidresponse.bid. Tracker
Method
Recommended Use
.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
.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 (in favor of eventtrackers).
.adm.native.imptrackers
Fired client-side (deprecated in favor of eventtrackers)
Invalid Traffic (IVT) tracking
.adm.native.jstracker
Fired client-side (deprecated in favor of eventtrackers)
Open Measurement SDK (OMSDK)
.adm.native.link.clicktrackers
Fired client-side
Click tracking (optional)
.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)
.ext.imptrackers
Fired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
"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",