S2S Bidding

Server-to-server (S2S) bidding lets your app server run the auction with BidMachine instead of running it on the client. The client SDK provides a bid token, your server uses it to request bids, and the winning bid payload is passed back to the client to load the ad.

Flow

1. Get a bid token — the client SDK generates an opaque token that encodes device/session signals.
2. Run a server-side auction — your app server sends the token to the BidMachine auction endpoint and receives a bid response payload.
3. Load the ad — the client passes the bid payload to load(activity, bidPayload) instead of calling load().

Step 1 — Get a Bid Token

Client-side token API in development

A public bid-token generator is in development and will be added in a future release. In the meantime, obtain the bid token out-of-band (e.g. through your server-side BidMachine integration) and use the load(activity, bidPayload) half below, which is available today.

Step 2 — Server-Side Auction

Your app server sends the bid token to the BidMachine S2S auction endpoint. The response contains a bid payload string that you pass back to the client. See the BidMachine S2S API documentation for endpoint details.

Step 3 — Load with Bid Payload

Pass the bid payload to load(activity, bidPayload) on any ad unit. It uses the same listener callbacks as a regular load() call.

Banner

val banner = BannerAd(activity, sdk, placementId = "YOUR_PLACEMENT_ID", size = BannerAdSize.Banner)
banner.listener = object : BannerListener {
    override fun onAdLoaded(adInfo: AdInfo) {
        adContainer.addView(banner)
    }
    override fun onAdLoadFailed(adInfo: AdInfo?, error: BidMachineError) {
        Log.e("BidMachine", "Banner load failed: ${error.message}")
    }
    override fun onAdShown(adInfo: AdInfo) {}
    override fun onAdShowFailed(adInfo: AdInfo?, error: BidMachineError) {}
    override fun onAdClicked(adInfo: AdInfo) {}
    override fun onAdExpired(adInfo: AdInfo) {}
    override fun onAdRevenuePaid(adInfo: AdInfo) {}
}

banner.load(activity, bidPayload)

Interstitial

val ad = InterstitialAd(sdk, placementId = "YOUR_PLACEMENT_ID")
ad.listener = object : InterstitialListener {
    override fun onAdLoaded(adInfo: AdInfo) {
        ad.show(activity)
    }
    override fun onAdLoadFailed(adInfo: AdInfo?, error: BidMachineError) {
        Log.e("BidMachine", "Interstitial load failed: ${error.message}")
    }
    override fun onAdShowFailed(adInfo: AdInfo?, error: BidMachineError) {}
    override fun onAdShown(adInfo: AdInfo) {}
    override fun onAdClicked(adInfo: AdInfo) {}
    override fun onAdClosed(adInfo: AdInfo) {}
    override fun onAdExpired(adInfo: AdInfo) {}
    override fun onAdRevenuePaid(adInfo: AdInfo) {}
}

ad.load(activity, bidPayload)

Rewarded

val ad = RewardedAd(sdk, placementId = "YOUR_PLACEMENT_ID")
ad.listener = object : RewardedListener {
    override fun onAdLoaded(adInfo: AdInfo) {
        ad.show(activity)
    }
    override fun onAdLoadFailed(adInfo: AdInfo?, error: BidMachineError) {
        Log.e("BidMachine", "Rewarded load failed: ${error.message}")
    }
    override fun onAdShowFailed(adInfo: AdInfo?, error: BidMachineError) {}
    override fun onAdShown(adInfo: AdInfo) {}
    override fun onAdClicked(adInfo: AdInfo) {}
    override fun onAdClosed(adInfo: AdInfo) {}
    override fun onAdRewarded(adInfo: AdInfo, reward: Reward?) {}
    override fun onAdExpired(adInfo: AdInfo) {}
    override fun onAdRevenuePaid(adInfo: AdInfo) {}
}

ad.load(activity, bidPayload)