Configuration
PrebidMobile holds the global SDK settings. Every setter returns a Future that completes once the native SDK has applied the value; settings apply to every request made afterwards.
Initialization
await PrebidMobile.initializeSdk(
prebidServerUrl: 'https://your-pbs.example.com/openrtb2/auction',
accountId: 'your-account-id',
nonTrackingUrl: 'https://your-pbs-no-tracking.example.com/openrtb2/auction', // iOS
completion: (status, error) => debugPrint('Prebid: $status $error'),
);
| Status | Meaning |
|---|---|
PrebidInitializationStatus.succeeded | Ready. Also reported when the status check is disabled. |
PrebidInitializationStatus.serverStatusWarning | Prebid Server's /status endpoint didn't answer as expected; requests still go out. |
PrebidInitializationStatus.failed | The SDK couldn't initialize (for example an invalid server URL). |
- Calling
initializeSdkagain (for example after a hot restart) completes immediately and applies the new server URL. nonTrackingUrliOS only is used instead ofprebidServerUrlwhile the user hasn't authorized tracking (App Tracking Transparency).PrebidMobile.isSdkInitializedtells whether initialization completed with a usable status.- Call
setDisableStatusCheck(true)beforeinitializeSdkto skip the/statusrequest. - With Google Mobile Ads in the app (the GAM or AdMob package, or
google_mobile_ads),initializeSdkpasses its version to Prebid's compatibility check, which logs a warning for a version Prebid doesn't support.
Switching account or server at runtime
setPrebidServerAccountId and setPrebidServerUrl change the account and auction endpoint for the next auctions without initializing again (no /status check runs). Ads that are already loaded or refreshing keep their bids until their next auction.
await PrebidMobile.setPrebidServerAccountId('another-account');
await PrebidMobile.setPrebidServerUrl('https://other-pbs.example.com/openrtb2/auction');
final account = await PrebidMobile.getPrebidServerAccountId();
final url = await PrebidMobile.getPrebidServerUrl(); // null before one is set
On iOS, setPrebidServerUrl throws a PlatformException for a malformed URL, and a nonTrackingUrl passed to initializeSdk stays in effect for users who haven't authorized tracking; getPrebidServerUrl returns the URL the current user's auctions use.
Requests
| Method | Description |
|---|---|
setTimeoutMillis(int) | Bid request timeout in milliseconds. |
getTimeoutMillisDynamic() iOS only | The timeout Prebid adopted from Prebid Server's response, or null while it uses setTimeoutMillis's. Prebid Android writes the server's value into getTimeoutMillis() instead. |
setCustomHeaders(Map<String, String>) | Extra HTTP headers on every bid request. |
setShareGeoLocation(bool) | Send the device location when the app has location permission. |
setPbsDebug(bool) | Ask Prebid Server for debug output (test: 1). |
setCustomStatusEndpoint(String) | Override the /status URL used at initialization. |
setLogLevel(PrebidLogLevel) | Native SDK log verbosity: debug, verbose, info, warn, error, severe, or none. |
setLogListener(listener) | Prebid's log messages to your code instead of the console (see Debugging). |
setLocationUpdatesEnabled(bool), getLocationUpdatesEnabled() iOS only | Prebid's own Core Location updates for device.geo (default true). |
setPrebidServerAccountId(String), getPrebidServerAccountId() | The Prebid Server account, switchable at runtime. |
setPrebidServerUrl(String), getPrebidServerUrl() | The auction endpoint, switchable at runtime. |
Prebid Server flags
| Method | Request field |
|---|---|
setIncludeWinners(bool) | ext.prebid.targeting.includewinners |
setIncludeBidderKeys(bool) | ext.prebid.targeting.includebidderkeys |
setAuctionSettingsId(String?) | Request-level stored request ID (ext.prebid.storedrequest.id), the account ID by default |
setFilterOutUncachedBids(bool) | Drop bids whose Prebid Cache entry failed and promote the next cached bid (topBidFiltered in responses). |
setShouldAssignNativeAssetId(bool) | Number native request assets sequentially, for creatives that reference assets by ID. |
setEidsPlacement(PrebidEidsPlacement) | Send external IDs in user.eids (OpenRTB 2.6), user.ext.eids (2.5) or both. |
Reading the settings
Each setting above has a getter that reads the native SDK's current value, e.g. PrebidMobile.getTimeoutMillis(), getPbsDebug(), getShareGeoLocation(), getCustomHeaders(), getStoredAuctionResponse(), getStoredBidResponses(), getCustomStatusEndpoint(), getShouldAssignNativeAssetId(), getFilterOutUncachedBids(), getEidsPlacement(), getIncludeWinners(), getIncludeBidderKeys(), getAuctionSettingsId() and getDisableStatusCheck().
Rendering
| Method | Description |
|---|---|
setCreativeFactoryTimeout(int), getCreativeFactoryTimeout() | Milliseconds an HTML creative may take to render (default 6000). |
setCreativeFactoryTimeoutPreRenderContent(int), getCreativeFactoryTimeoutPreRenderContent() | The same for pre-rendered video and interstitial content (default 30000). |
setUseCacheForReportingWithRenderingApi(bool), getUseCacheForReportingWithRenderingApi() | Ask Prebid Server to cache Rendering API bids (ext.prebid.cache) for analytics that report through Prebid Cache. Default false. |
getOmsdkVersion() | Version of the Open Measurement SDK bundled with Prebid. |
Prebid Server can override both creative factory timeouts per account in its responses, so the getters may return a different value after an auction. On iOS, creating an Original API ad unit turns useCacheForReportingWithRenderingApi on: that is how Prebid iOS asks for caching for the Original API.
External user IDs
Identity providers' IDs go to bidders in user.eids:
await PrebidMobile.setExternalUserIds([
ExternalUserId(source: 'uidapi.com', identifier: 'uid2-abc-123', atype: 3),
ExternalUserId(
source: 'liveramp.com',
identifier: 'lr-def-456',
atype: 3,
inserter: 'your-company.com',
),
// Several IDs from one source share one entry.
ExternalUserId.withUids(
source: 'adserver.org',
uids: [
UserUniqueId(id: 'tdid-1', atype: 1, ext: {'rtiPartner': 'TDID'}),
UserUniqueId(id: 'tdid-2', atype: 3),
],
),
]);
final ids = await PrebidMobile.getExternalUserIds();
await PrebidMobile.clearExternalUserIds();
Each ExternalUserId is one user.eids entry: a source, its uids and the OpenRTB 2.6 inserter, matcher and mm fields, plus the entry's ext. The default constructor makes an entry with one ID (identifier, atype: 1 device, 2 person-based, 3 user); ExternalUserId.withUids takes several UserUniqueIds, each with its own ext. getExternalUserIds returns the entries the same way.
SharedID
Prebid's first-party ID, stored on the device:
await PrebidMobile.setSendSharedId(true); // send it in user.eids
final sharedId = await PrebidMobile.getSharedId();
await PrebidMobile.resetSharedId(); // a new ID on the next request
Testing helpers
Stored responses, the bid inspector and SDK version checks are on the Debugging page.