Skip to main content
Version: v1.1.0

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'),
);
StatusMeaning
PrebidInitializationStatus.succeededReady. Also reported when the status check is disabled.
PrebidInitializationStatus.serverStatusWarningPrebid Server's /status endpoint didn't answer as expected; requests still go out.
PrebidInitializationStatus.failedThe SDK couldn't initialize (for example an invalid server URL).
  • Calling initializeSdk again (for example after a hot restart) completes immediately and applies the new server URL.
  • nonTrackingUrl iOS only is used instead of prebidServerUrl while the user hasn't authorized tracking (App Tracking Transparency).
  • PrebidMobile.isSdkInitialized tells whether initialization completed with a usable status.
  • Call setDisableStatusCheck(true) before initializeSdk to skip the /status request.
  • With Google Mobile Ads in the app (the GAM or AdMob package, or google_mobile_ads), initializeSdk passes 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​

MethodDescription
setTimeoutMillis(int)Bid request timeout in milliseconds.
getTimeoutMillisDynamic() iOS onlyThe 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 onlyPrebid'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​

MethodRequest 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​

MethodDescription
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.