Header bidding in an app with Prebid Mobile

Sell in-app inventory through Prebid Mobile — which placement each app ad unit needs as a slot, what the ad server reads off an in-app request, what to check when the app gets nothing, and Prebid Mobile against a publisher’s own Prebid Server.

How-to network manager admin Account → Header Bidding

An app has no browser auction: Prebid Mobile asks a Prebid Server for each ad unit by its slot id, and the same header-bidding tag answers. This page covers what each app ad unit needs as a slot, what to check when the app gets nothing, and what changes when the Prebid Server is the publisher’s own. The server side — slot ids, our Prebid Server, their Prebid Server — is on Header bidding through a Prebid Server, and the example apps are the end-to-end reference for iOS and Android.

Who this is for

Network managers and admins who build the tag, and the app developer who receives the slot ids. The tag needs the access listed under Permissions.

Prerequisites

A Prebid Server for the app to call — Our Prebid Server, or their own set up as under Their Prebid Server, our setup.
A network id on the ad server, so the slot ids exist — see Slot ids.
A placement of a supported type for each app ad unit — see the table under In an app: what each slot needs.

Steps

Add one slot per app ad unit, on the placement type the table below names.
Save the tag, open Code → Our Prebid Server (or Their Prebid Server, our setup) and copy the slot ids and, on our server, the two SDK calls — see Our Prebid Server.
Hand the ids and the example apps to the app developer; each id is the configId of one ad unit.
If the app gets nothing, go through When the app gets nothing.

In an app: what each slot needs

Every Prebid Mobile ad unit in the app is one slot in the tag, and a slot answers one kind of creative: the impression’s media type — video, native, or banner — picks the path on our side, and a slot is built on one placement of one type. Two formats in the app are two slots with two ids, even when the creative is the same file.

Only four placement types can be slots. The picker lists the others closed off, each ending in not supported yet — Application Placement and Mobile Site Placement among them, which is where an in-app integration would otherwise start. Build the placements for an app on these:

Prebid Mobile ad unit	Placement type	Ad units on the slot
Banner (`BannerView` / `BannerAdUnit`, e.g. 300×250, 320×50)	Site Placement	The placement’s size. The app’s own request sizes are what the bid is matched against; a creative bids only in a size the app asked for.
In-banner video, interstitial video, rewarded video	Video Placement	Leave empty. The SDK plays the VAST it receives, so the creative is not size-matched.
Native (`NativeAd`)	Native Placement	Leave empty — a native bid is described by its assets, not by sizes.
Interstitial image, playable — anything full-screen that is not VAST	Non-standard Placement	Leave empty. See Full-screen and other Non-standard slots.

Name the slot after the ad unit it serves (mrec-home, interstitial-level-end) and the listing under 1. The slot ids becomes the app’s own configuration table. GAM ad unit and Fallback markup do nothing for an app.

What the ad server reads off an in-app request, so you know which of your settings apply:

app.bundle arrives as the app’s package, so the Package Name dimension and App Package targeting apply to in-app traffic. app.storeurl is deliberately not read as the page URL — every impression would otherwise report and target as the app store.
device.ifa is the user for frequency capping and everything else keyed on a user. It is ignored when lmt or dnt is set and when it is all zeros — what iOS returns when App Tracking Transparency is refused, and Android when personalisation is opted out; on iOS the vendor id the SDK sends in device.ext.ifv is used in its place, so capping keeps working for a reader who declined. Android sends no equivalent. On Android the app also needs the AD_ID permission, or Google Play Services withholds the id and every cap silently stops applying.
imp.bidfloor is honoured, as US dollars — see the floor case under Corner cases and gotchas.
Consent comes from the TCF string and GDPR flag the SDK carries — see Consent.

If the app renders through Google instead of through Prebid — the original API, where the SDK writes the bid’s price into a Google ad request as key-values — the Google Ad Manager line item section applies unchanged. A slot rendered by Prebid needs no Google ad unit and no line item.

Corner cases and gotchas

When the app gets nothing

The SDK has a small vocabulary, and each phrase points somewhere specific.

“Prebid server does not recognize Config Id” is the SDK’s wording for the server’s Stored Imp with ID=”…” not found: the auction ran, and no stored request answered to that id. In order of likelihood:

The id is not exactly what the tag lists. Both halves count: n1234-26 is one slot on one network. Copy it from 1. The slot ids rather than typing it.
The slot is not in the served set. Only slots on a tag that is saved, has Serve this tag on and is not deleted are served, and only slots that point at a placement. A tag paused to edit it stops bidding within a minute, and its ids drop out of the server’s answer once its cache of them expires.
The slot was removed and re-added. That is a new id; the app carries the old one.
You saved less than a minute ago. The ad servers refresh the served set every minute; the Prebid Server never caches a miss, so a new id resolves on the first auction after that.
The Prebid Server’s stored-request fetch timed out. Prebid Mobile sends no tmax on interstitial and rewarded requests, so the Prebid Server falls back to its own stored-request timeout — 50 ms by default in Prebid Server, less than one round trip to us — and reports the slot as not found; slots it already holds in cache keep working, which is why it looks intermittent and hits full-screen formats first. Whoever runs the Prebid Server raises its stored-request timeout (stored_requests_timeout_ms in Prebid Server’s own configuration); on pbs.eashb.com, ask Epom support or your account manager.
The Prebid Server is not yet reading this network’s slots. The network’s serving host answers /hb/stored-requests on its own; the Prebid Server has to be pointed at it when the network is set up. This message on a freshly configured network is the sign that has not happened yet — ask Epom support or your account manager.

“no winning bid in the bid response” with the id right: the account document on the server is missing its targeting block, so the SDK never sees hb_pb / hb_bidder on the bid and treats a priced bid as a loss — see Our Prebid Server. The same phrase appears when the Prebid Cache cannot be reached; both are on the server side.

A blank slot and no message is a no-fill. The ad server answered nothing, and the places to look are: the placement is not sold by an active tag (When a placement answers bids); no creative fits — a banner slot bids only in a size the app asked for; ordinary serving rules — targeting, caps and limits, and the GDPR policy for a reader whose IP is in the EEA and whose request carried no consent string; the Prebid Server’s auction budget is shorter than a round trip to us — Prebid Mobile sends no tmax on full-screen requests, so the server’s own auction_timeouts_ms decides, and a bid that arrives after it is a no-bid with context deadline exceeded in the response, never an error the app shows (whoever runs the Prebid Server sets the budget, and it has to be longer than the round trip to your serving host); or the ad unit was built before initializeSdk finished, so the request went out and the answer was never delivered — start the ad units from the SDK’s initialisation callback, as the example apps do.

A rewarded ad that closes like an interstitial — no close button held back, the reward granted on the SDK’s own terms — means the slot is not marked Rewarded; see Rewarded.

Prebid Mobile against their server

An app never bids in the browser: Prebid Mobile always calls a Prebid Server, and when that server is the publisher’s own, everything under Their Prebid Server, our setup applies plus what the SDK adds. The example apps are the end-to-end reference; this is the part that touches your side.

configId is the slot id. Prebid Mobile sends no bidder parameters from the app: it puts the configId into imp.ext.prebid.storedrequest.id and stops. Our host and placement key never appear in the app — they are in the stored document, which is why the address or the per-slot copies must be in place first.

The account is a stored request too, and it is theirs to file. The SDK sends the account id both as the account and as a request-level stored request. That account id comes from their Prebid Server host, not from us — we issue the serving host and the placement key, and nothing else; a publisher who asks their Epom contact for an account id is asking the wrong party. Our address answers a request-level id only for our own network id, so on their server the document has to live in their own backend, under the account id their host issued, and it needs the targeting block or the rendering API displays nothing it receives:

{
  "id": "their-account-id",
  "ext": { "prebid": { "targeting": {
    "includewinners": true,
    "includebidderkeys": true
  } } }
}

Their server needs a Prebid Cache. The rendering API caches creatives for display; without one a good bid answers no winning bid in the bid response. We answer video with inline VAST and depend on no cache ourselves, so this is entirely on their side.

Full-screen slots. An interstitial or rewarded request — instl=1 or rwdd=1 — is answered through a slot built on a Non-standard Placement whose ad units are left empty, so its document carries no banner block. A request that names a size is answered at that size; one that names none is answered at the device’s own width and height; the creative’s own size is not matched — see Full-screen and other Non-standard slots.

App identity and device ids are read exactly as under In an app: what each slot needs.

Per-role notes

Network manager — builds the tag and hands over the slot ids.
Publisher — their developer puts the ids into the app; see Header bidding: what a publisher installs.
Can View share — sees the site’s tags but cannot save or delete them; see the per-role notes on the main page.