Bid Responses
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 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. Note that loss code “103 Lost to a Bid for a PMP Deal” is 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. 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
CDATAconstruct.CDATAin 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.)
- All double quotes are escaped as
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 (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 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 | 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 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. | 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) | 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:
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. 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 (available as of SDK 11.1.1). | 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. 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. 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. | 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 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 Fields
The following table shows the tracking fields available to demand-side platforms, and their recommended uses.
bidresponse.bid. Tracker | Method | Recommended Use |
|---|---|---|
.adm |
|
|
.adm.native.eventtrackers | Fired client-side |
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) |
.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) |
.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 |
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" } ]}