# SDK Bidding Guidelines ## SDK Bidding Guidelines This article provides requirements for bid requests and responses for SDK Bidding with DT Exchange. For more information, see [DT Exchange SDK Bidding Process](https://docs.digitalturbine.com/dt-exchange/publishers/getting-started-with-dt-exchange/sdk-bidding-process). ### Bid Request Specifications DT expects to receive properly structured bid requests per the [IAB OpenRTB API](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) specification from the mediation platform. DT uses the following attributes along with an SDK-generated token that authenticates the bid request. | ATTRIBUTE | TYPE | DESCRIPTION | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BidRequest.id` | String | Unique ID for the bid request. | | `app.ext.token` | String | Token generated by DT Exchange SDK for the bid request. The token can be as large as 6 kb. | | `BidRequest.tmax` | String | Time to respond. To ensure DT Exchange can accept bids from as many bidders as possible, DT recommends setting the time to respond value at 1000 ms or longer. | | `device.ip` | String | IPv4 address closest to the device. | | `device.ipv6` | String | IPv6 address closest to the device. | | `device.ua` | String | User agent string containing device data. | | `imp.displaymanager` | String | Name of the ad mediation partner. | | `imp.displaymanagerver` | String | Version of ad mediation partner. | | `imp.bidfloor` | String | Minimum bid price for the impression expressed in CPM. DT supports precision up to 5 digits. | | `imp.tagid` | String | Placement ID. | #### Example Bid Request The following is an example of a bid request. {% code title="JSON" %} ```json { "id": "a97cc130-7387-11f0-9f5f-a1ac0196517a_1912357094", "imp": [ { "id": "1", "banner": { "w": 1080, "h": 2112 }, "video": { "mimes": [ "video/mp4" ], "w": 1080, "h": 2112, "linearity": 2 }, "instl": 1, "tagid": "2055013", "bidfloor": 0.01, "secure": 1, "ext": { "gpid": "q7nmm84lbmzqd64w" } } ], "app": { "bundle": "com.bundle.example", "ext": { "sessionDepth": 4, "token": "CgUKAzEuMhKnAQqkAU1vemlsbGEvNS4wIChMaW51eDsgQW5kcm9pZCAxNTsgU00tUzkyOE4gQnVpbGQvQVAzQS4yNDA5MDUuMDE1LkEyOyB3dikgQXBwbGVXZWJLaXQvN==" } }, "device": { "ext": { "app_set_id": "1234567-78b1-bcdf-8b01-fbc738e142f3" }, "os": "android", "ip": "127.0.0.0", "h": 2112, "language": "ko", "dnt": 0, "ua": "Mozilla/5.0 (Linux; Android 15; SM-S928N Build/AP3A.240905.015.A2; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.179 Mobile Safari/537.36", "devicetype": 4, "geo": { "country": "KR" }, "lmt": 0, "osv": "15", "w": 1080, "model": "SM-S928N", "connectiontype": 5, "make": "samsung", "ifa": "12345678-a489-1234-be0c-3625cf35b1be" }, "user": { "ext": { "consent": "1" } }, "test": 0, "at": 1, "tmax": 1500, "cur": [ "USD" ], "source": { "tid": "a97cc130-7387-11f0-9f5f-a1ac0196517a_1912357094" }, "regs": {} } ``` {% endcode %} ### Bid Response Specifications DT determines a winning bid and sends a bid response back to the mediation platform to compete against other mediated networks. The bid response follows the [IAB OpenRTB API](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) specification and contains the following attributes required for processing the bid and rendering the ad on the device: | ATTRIBUTE | TYPE | DESCRIPTION | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BidResponse.id` | String | ID of the bid response, matching the bid request ID. | | `seatbid.bid.id` | String | Bidder-generated ID for the bid. | | `seatbid.bid.impid` | String | ID of the `imp` object in the related bid request. | | `seatbid.bid.price` | Float | Bid price expressed as CPM, although the actual transaction is for a unit impression only. | | `seatbid.bid.adm` | String | Ad markup to be rendered. This is a hashed value to be passed to the SDK. | | `seatbid.bid.nurl` | String | Win notice URL to call when a bid wins. The nURL supports substitution macros. For more information, see [Supported Macros](#biddingmacros). | | `seatbid.bid.lurl` | String | Loss notice URL to call when a bid is lost. The lURL supports substitution macros. For more information, see [Supported Macros](#biddingmacros). | | `seatbid.bid.burl` | String | Billing notice URL to call when a billable event occurs. When forwarding bURL notifications through proxy servers, use the `X‑Forwarded‑For` and `User‑Agent` headers to preserve details about the proxy chain and user agent. | #### Supported Macros DT supports the following substitution macros for event notifications. **nURL Substitution Macros** | MACRO | nURL PARAMETER | DESCRIPTION | EXAMPLE | | -------------------- | -------------- | ----------------------------------------------------- | ------------------------------ | | `AUCTION_PRICE` | `price` | The final price to be paid on impression. | `price=${AUCTION_PRICE}` | | `AUCTION_BID_TO_WIN` | `minBid` | The minimum bid that was required to win the auction. | `minBid=${AUCTION_BID_TO_WIN}` | **lURL Substitution Macros** | MACRO | lURL PARAMETER | DESCRIPTION | EXAMPLE | | --------------- | -------------- | -------------------------------------------------------------------------------------------------------- | -------------------------- | | `AUCTION_LOSS` | `lossCode` | The loss reason code, indicating why the bid lost the auction, for example, lost on price, timeout, etc. | `lossCode=${AUCTION_LOSS}` | | `AUCTION_PRICE` | `price` | The final winning price to be paid on impression. | `price=${AUCTION_PRICE}` | #### Ad Expiration DT sets the following time limits for rendering an ad. After these times elapse, the impression is not billable: * Banner: 30 minutes * Interstitial: 60 minutes * Rewarded: 60 minutes #### Example Bid Response {% code title="JSON" %} ```json { "id": "521d96b0-7389-11f0-a14d-fb5de7745fe3_1123125237", "seatbid": [ { "bid": [ { "id": "8531704193319338877", "price": 1.0382123166023163, "nurl": "https://notifications-gke-sdk-bidding-a.fyber.com/nurl/{mediationName}?s=8531704193319338877&persister=new&deploymentEnv=SDKBidding&price=${AUCTION_PRICE}&minBid=${AUCTION_BID_TO_WIN}&adTime=1754569407912", "burl": "https://notifications-gke-sdk-bidding-a.fyber.com/burl/{mediationName}?s=8531704193319338877&persister=new&deploymentEnv=SDKBidding&adTime=1754569407912", "lurl": "https://notifications-gke-sdk-bidding-a.fyber.com/lurl/{mediationName}?s=8531704193319338877&persister=new&deploymentEnv=SDKBidding&lossCode=${AUCTION_LOSS}&price=${AUCTION_PRICE}&adTime=1754569407912", "adm": "hODVkNDkyLWE0ODktNDUyMS1iZTBjLTM2MjVjZjM1bDEbZcIDAwjuAuIDAggA+gMwChNmbXBfZW5kY2FyZF9hbmRyb2lkEhlGbXBFbmRjYXJkRW5hYmxlZF92MS4xLjE0+gM9Chp2aWRlb19jbGlja2Fia==", "ext": { "test": 0 } } ] } ] } ``` {% endcode %} ### HTTP Configuration Use the following HTTP configuration for SDK Bidding with DT Exchange: | SETTING | CONFIGURATION | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Host URL | `bidding.fyber.com` | | Bidding Endpoint |

/bid/{mediationProviderName}
DT provides the mediationProviderName as a part of initial integration setup. For more information, contact your DT representative.

| | Protocol |

DT accepts the following protocols:

| | Headers | `Accept-Encoding: gzip` | | Timeout | 620 seconds | ### Testing Bidding Integration Before going live with your DT Exchange integration, DT can facilitate testing by configuring test placements to always fill with specific test ads. For more information, contact your DT representative.