Prebid SDK Global Parameters - Android

• How to Read this Guide
• Prebid Global Properties and Methods
  • Prebid Class Global Properties
  • Prebid Class Global Methods
    • setPrebidServerAccountId()
    • setPrebidServerHost()
    • setCustomStatusEndpoint()
    • setTimeoutMillis()
    • setShareGeoLocation()
    • setIncludeWinnersFlag()
    • setIncludeBidderKeysFlag()
    • setStoredAuctionResponse()
    • addStoredBidResponse()
    • clearStoredBidResponses()
    • setLogLevel
    • setPbsDebug()
    • assignNativeAssetID()
    • setCreativeFactoryTimeout()
    • setCreativeFactoryTimeoutPreRenderContent()
    • setCustomHeaders()
    • setCustomLogger()
• Consent Management Parameters
  • GDPR / TCF-EU
    • Setting TCF-EU Values with the API
    • Getting Consent Values from the CMP
  • CCPA / US Privacy
  • COPPA
  • Global Privacy Platform (GPP)
• Open Measurement SDK (OMSDK) API
  • Partner Name
  • Partner Version
  • Banner API Code
• First Party Data
  • User FPD
  • Inventory FPD
  • Controlling Bidder Access to FPD
• User Identity
  • Prebid SDK API Access
  • IDs that Require Additional SDKs
    • Unified ID 2.0 (UID2)
• Targeting Class Methods
  • setBundleName()
  • setDomain()
  • setPublisherName()
  • setStoreUrl()
  • setOmidPartnerName()
  • setOmidPartnerVersion()
  • setUserLatLng()
• Arbitrary OpenRTB
• Further Reading

How to Read this Guide

This page documents various global parameters you can set on the Prebid SDK for Android. It describes the properties and methods of the Prebid SDK that allow you to supply important parameters to the header bidding auction.

Specifically, app developers should consider each of these general sections:

• Prebid SDK class parameters: these cover behavior of the SDK. Some values are required like a Prebid Server.
• Privacy / Consent Management parameters: we recommend developing a clear plan for user privacy with your legal counsel.
• First Party Data: data about the app or user that helps bidders choose an appropriate ad.

Note that the SDK’s Targeting class uses the term “Targeting” loosely. It’s mostly about passing data to bidders that would help improve auction results. But there are also fields and methods in the Targeting class that convey privacy data, Open Measurement info, and other data used beyond actual bid targeting.

Prebid Global Properties and Methods

The Prebid class is a singleton that enables you to apply certain global settings.

Prebid Class Global Properties

All of these properties of the Prebid class can be set on the shared object like this:

Prebid.shared.sendMraidSupportParams=true

Prebid Class Global Methods

setPrebidServerAccountId()

Your Prebid Server team will tell you whether this is required or not and if so, the value. See the initialization page for Android.

setPrebidServerHost()

This is where the Prebid SDK will send the auction information.

Signature:

func setPrebidServerHost(host: String)

Parameters:

Examples:

PrebidMobile.setPrebidServerHost(Host.APPNEXUS)
PrebidMobile.setPrebidServerHost(Host.RUBICON)
PrebidMobile.setPrebidServerHost(Host.createCustomHost("https://prebidserver.example.com/openrtb2/auction"))

setCustomStatusEndpoint()

Signature:

    public static void setCustomStatusEndpoint(String url) {

Parameters:

setTimeoutMillis()

The Prebid SDK timeout. When this number of milliseconds passes, the Prebid SDK returns control to the ad server SDK to fetch an ad without Prebid bids. See the initialization page for Android.

setShareGeoLocation()

If this flag is true AND the app collects the user’s geographical location data, Prebid Mobile will send the user’s lat/long geographical location data to the Prebid Server. The default is false.

setIncludeWinnersFlag()

If true, Prebid sdk will add the includewinners flag inside the targeting object described in PBS Documentation . This is needed if you’ve set up line items in an ad server in “Send Top Bid” mode, as it’s what creates the key value pairs like hb_pb.

Signature:

    public static void setIncludeWinnersFlag(boolean includeWinners)

Parameters:

setIncludeBidderKeysFlag()

If true, Prebid sdk will add the includebidderkeys flag inside the targeting object described in PBS Documentation . This is needed if you’ve set up line items in an ad server in “Send All Bids” mode, as it’s what creates the key value pairs like hb_pb_bidderA.

Signature:

    public static boolean setIncludeBidderKeysFlag(boolean includeBidderKeys) {

Parameters:

setStoredAuctionResponse()

For testing and debugging. Get this value from your Prebid Server team. It signals Prebid Server to respond with a static response from the Prebid Server Database. See more information on stored auction responses.

Signature:

public static void setStoredAuctionResponse(@Nullable String storedAuctionResponse)

Parameters:

addStoredBidResponse()

Stored Bid Responses are for testing and debugging similar to Stored Auction Responses (see the Global Properties above). They signal Prebid Server to respond with a static pre-defined response, except Stored Bid Responses actually exercise the bidder adapter. For more information on how stored bid responses work, refer to the Prebid Server endpoint doc. Your Prebid Server team will help you determine how best to setup test and debug.

Signature:

void addStoredBidResponse(String bidder, String responseId)

Parameters:

clearStoredBidResponses()

This method clears any stored bid responses. It doesn’t take any parameters.

Signature:

void clearStoredBidResponses()

Parameters: none.

setLogLevel

Controls the level of logging output to the console.

Signature:

    public static void setLogLevel(LogLevel logLevel)

Parameters:

setPbsDebug()

Adds the debug flag (test:1) on the outbound http call to the Prebid Server. The test flag signals to the Prebid Server to emit the full resolved request and the full Bid Request and Bid Response to and from each bidder.

Signature:

public static void setPbsDebug(boolean pbsDebug)

Parameters:

assignNativeAssetID()

Whether to automatically assign an assetID for a Native ad. Default is false.

Signature:

    public static void assignNativeAssetID(boolean assignNativeAssetID) {

Parameters:

setCreativeFactoryTimeout()

Controls how long a banner creative has to load before it is considered a failure.

Signature:

    public static void setCreativeFactoryTimeout(int creativeFactoryTimeout)

Parameters:

setCreativeFactoryTimeoutPreRenderContent()

Controls how much time video and interstitial creatives have to load before it is considered a failure.

Signature:

    public static void setCreativeFactoryTimeoutPreRenderContent(int creativeFactoryTimeoutPreRenderContent)

Parameters:

setCustomHeaders()

This method enables you to customize the HTTP call to Prebid Server.

Signature:

    public static void setCustomHeaders(@Nullable HashMap<String, String> customHeaders)

Parameters:

setCustomLogger()

Define a custom PrebidLogger object.

Signature:

    public static void setCustomLogger(@NonNull PrebidLogger logger)

Parameters:

Consent Management Parameters

This section describes how app developers can provide info on user consent to the Prebid SDK and how SDK behaves under different kinds of restrictions.

GDPR / TCF-EU

Prebid Mobile supports IAB TCF. For a general overview of Prebid Mobile support for GDPR, see the Prebid Mobile Guide to Privacy Regulation.

There are two ways to provide information on user consent to the Prebid SDK:

• Explicitly via Prebid SDK API: publishers can provide TCF data via Prebid SDK’s ‘Targeting’ class.
• Implicitly set through the Consent Management Platform (CMP): Prebid SDK reads the TCF data stored in the SharedPreferences. This is the preferred approach.

The Prebid SDK prioritizes values set explicitly through the API over those stored by the CMP. If the publisher provides TCF data both ways, the values set through the API will be sent to the PBS, and values stored by the CMP will be ignored.

Setting TCF-EU Values with the API

Prebid SDK provides three properties to set TCF consent values explicitly, though this method is not preferred. Ideally, the Consent Management Platform will set these values – see the next section.

If you need to set the values directly, here’s how to indicate that the user is subject to GDPR:

TargetingParams.setSubjectToGDPR(true)

To provide the consent string:

TargetingParams.setGDPRConsentString("BOMyQRvOMyQRvABABBAAABAAAAAAEA")

To set the purpose consent:

TargetingParams.setPurposeConsents("100000000000000000000000")

Related functions: isSubjectToGDPR(), getGDPRConsentString(), getPurposeConsent(int index), getPurposeConsents(), getDeviceAccessConsent()

Getting Consent Values from the CMP

Prebid SDK reads the values for the following keys from the SharedPreferences object:

• IABTCF_gdprApplies - indicates whether the user is subject to GDPR
• IABTCF_TCString - full encoded TC string
• IABTCF_PurposeConsents - indicates the consent status for the purpose.

For more detailed information, read the In-App Details section of the TCF.

Publishers shouldn’t explicitly assign values for these keys unless they have a custom-developed Consent Management Platform (CMP). If the publisher wants to provide this data to the Prebid SDK, they should use the explicit APIs described above.

Here’s how Prebid SDK processes CMP values:

• It reads CMP values during the initialization and on each bid request, so the latest value is always used.
• It doesn’t verify or validate CMP values in any way

CCPA / US Privacy

The California Consumer Protection Act prompted the IAB to implement the “US Privacy” protocol.

Prebid SDK reads and sends USP/CCPA signals according to the US Privacy User Signal Mechanism and OpenRTB extension.

Prebid SDK reads the value for the IABUSPrivacy_String key from SharedPreferences and sends it in the regs.ext.us_privacy object of the OpenRTB request.

COPPA

The Children’s Online Privacy Protection Act of the United States is a way for content producers to declare that their content is aimed at children, which invokes additional privacy protections.

Prebid SDK follows the OpenRTB 2.6 spec and provides an API to indicate whether the current content falls under COPPA regulation. Publishers can set the respective flag using the targeting API:

TargetingParams.setSubjectToCOPPA(true)

Prebid SDK passes this flag in the regs.coppa object of the bid requests.

If you’re app developer setting this COPPA flag, we recommend you also:

• set the shareGeoLocation property to false
• avoid passing any sensitive first party data

Global Privacy Platform (GPP)

A Consent Management Platform (CMP) utilizing IAB’s Global Privacy Protocol is a comprehensive way for apps to manage user consent across multiple regulatory environments.

Since version 2.0.6, Prebid SDK reads and sends GPP signals:

• The GPP string is read from IABGPP_HDR_GppString in SharedPreferences. It is sent to Prebid Server on regs.gpp.
• The GPP Section ID is likewise read from IABGPP_GppSID. It is sent to Prebid Server on regs.gpp_sid.

Open Measurement SDK (OMSDK) API

Defining OMSDK values is only relevant for the ‘Bidding-Only’ Prebid integration with GAM. In this case the creative is rendered by GMA SDK and publishers should provide OMID description in the bid request. If you use Prebid SDK as a rendering engine you shouldn’t use these properties – it sends them automaticaly according to the current OMID setup.

OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters by way of Prebid Server, indicating that the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code.

There are three components to signaling support for OMSDK:

• Partner Name
• Partner Version
• Banner API code

Partner Name

The IAB OMSDK compliant partner name responsible for integrating with the OMSDK spec.

TargetingParams.setOmidPartnerName("Google")

Partner Version

The OMSDK version number for the integration partner.

TargetingParams.setOmidPartnerVersion("1.0");

Banner API Code

The following code lets bidders know that Open Measurement is being used for this adunit:

let parameters = BannerParameters()
parameters.api = [Signals.Api.OMID_1]

First Party Data

First Party Data (FPD) is information about the app or user known by the developer that may be of interest to advertisers.

• User FPD includes details about a specific user like “frequent user” or “job title”. This data if often subject to regulatory control, so needs to be specified as user-specific data. Note that some attributes like health status are limited in some regions. App developers are strongly advised to speak with their legal counsel before passing User FPD.
• Inventory FPD includes details about the particular part of the app where the ad will displayed like “sports/basketball” or “editor 5-star rating”.

User FPD

Prebid SDK provides a number of properties in the Targeting class for setting user-oriented First Party Data.

void addUserData(String key, String value)

void updateUserData( String key, Set<String> value)

void removeUserData(String key)

void clearUserData()

Map<String, Set<String>> getUserDataDictionary() {

void addUserKeywords(Set<String> keywords) {

void removeUserKeyword(String keyword) {

void clearUserKeywords() {

String getUserKeywords() {

Set<String> getUserKeywordsSet() {

Example:

TargetingParams.addUserData("globalUserDataKey1", "globalUserDataValue1")

Note: The ‘UserData’ functions end up putting data into the OpenRTB user.ext.data object while the ‘UserKeywords’ functions put data into user.keywords.

Inventory FPD

Prebid SDK provides a number of methods in the Targeting class for setting content-oriented First Party Data.

void addExtData(String key, String value)

void updateExtData(String key, Set<String> value)

void removeExtData(String key)

Map<String, Set<String>> getExtDataDictionary()

void addExtKeyword(String keyword)

void addExtKeywords(Set<String> keywords)

void removeExtKeyword(String keyword)

void clearExtKeywords()

Set<String> getExtKeywordsSet()

Example:

Targeting.addExtData("globalContextDataKey1", "globalContextDataValue1")

Controlling Bidder Access to FPD

Prebid Server will let you control which bidders are allowed access to First Party Data. Prebid SDK collects this an Access Control List with the following methods:

void addBidderToAccessControlList(String bidderName)

void removeBidderFromAccessControlList(String bidderName)

void clearAccessControlList()

Set<String> getAccessControlList()

Example:

Targeting.addBidderToAccessControlList("bidderA")

User Identity

Mobile apps traditionally rely on IDFA-type device IDs for advertising, but there are other User ID systems available to app developers and more will be made available in the future. Prebid SDK supports two ways to maintain Extended User ID (EID) details:

• A global property - in this approach, the app developer sets the IDs while initializing the Prebid SDK. This data persists only for the user session.
• Local storage - the developer can choose to store the IDs persistently in local storage and Prebid SDK will utilize them on each bid request.

Any identity vendor’s details in local storage will be sent to Prebid Server unadulterated. If user IDs are set both in the property and entered into local storage, the property data will prevail.

Note that the phrase “EID” stands for “Extended IDs” in OpenRTB 2.6, but for historic reasons, Prebid SDK methods use the word “external” rather than “extended”. Please consider the phrase “external ID” a synonym for “extended ID”.

Prebid SDK API Access

Prebid SDK supports passing an array of EIDs at auction time with the function storeExternalUserId, which is globably scoped. It is sufficient to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session.

void storeExternalUserId(<ExternalUserId> externalUserIds)

List<ExternalUserId> fetchStoredExternalUserIds()

ExternalUserId fetchStoredExternalUserId(@NonNull String source) 

void removeStoredExternalUserId(@NonNull String source) {

void clearStoredExternalUserIds() {

Example:

  // User Id from External Third Party Sources
  ArrayList<ExternalUserId> externalUserIdArray = new ArrayList<>();
  externalUserIdArray.add(new ExternalUserId("adserver.org", "111111111111", null, new HashMap() {
    {
        put ("rtiPartner", "TDID");
    }
}));

  externalUserIdArray.add(new ExternalUserId("netid.de", "999888777", null, null));
  externalUserIdArray.add(new ExternalUserId("criteo.com", "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N", null, null));
  externalUserIdArray.add(new ExternalUserId("liveramp.com", "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg", null, null));
  externalUserIdArray.add(new ExternalUserId("sharedid.org", "111111111111", 1, null));
}));

//Set External User IDs
PrebidMobile.storeExternalUserId(externalUserIdArray);

IDs that Require Additional SDKs

Certain identity vendors require an external dependency to generate user identity and then to pass it via Prebid SDK. Please note that these are references to a 3rd party code and Prebid has not inspected it. Links to the documentations of those references will be listed in this section.

Unified ID 2.0 (UID2)

UID2 provides a native library for automatically updating latest UID2 token stored inside UID2 SDK for Android into Prebid’s external user’s ID list.

App developers are not required to manually call PrebidMobile.setExternalUserId method as the native library will do so automatically.

Note:

• Github repo
• UID2 Android Integration Documentation
• UID2+Prebid Integration Instruction

Targeting Class Methods

There are several other fields app developers may want to set to give bidders additional information about the auction. Prebid recommends that app developers consider setting the following values for best auction performance:

• setBundleName()
• setPublisherName()
• setStoreUrl()

setBundleName()

Define the OpenRTB app.bundle field.

Signature:

void setBundleName(String bundleName) {

Parameters:

Related function: getBundleName().

setDomain()

Define the OpenRTB app.domain field.

Signature:

void setDomain(String domain)

Parameters:

Related function: getDomain().

setPublisherName()

Define the OpenRTB app.publisher.name field.

Signature:

void setPublisherName(String publisherName)

Parameters:

Related function: getPublisherName().

setStoreUrl()

Define the OpenRTB app.storeurl field.

Signature:

void setStoreUrl(String storeUrl)

Parameters:

Related function: getStoreUrl().

setOmidPartnerName()

Define the OpenRTB source.ext.omidpn field.

Signature:

setOmidPartnerName(@Nullable String omidPartnerName)

Parameters:

Related function: getOmidPartnerName().

setOmidPartnerVersion()

Define the OpenRTB source.ext.omidpv field.

Signature:

setOmidPartnerVersion(@Nullable String omidPartnerVersion)

Parameters:

Related function: getOmidPartnerVersion().

setUserLatLng()

Sets the device location for buyer targeting. It’s incumbent upon to the app developer to make sure they have permission to read this data. Prebid Server may remove it under some privacy scenarios.

Signature:

void setUserLatLng( Float latitude, Float longitude)

Parameters:

Arbitrary OpenRTB

(requires SDK v2.2.1)

While there are many specific methods for adding data to the request detailed in this document, OpenRTB is big and it moves quickly. To cover scenarios not already covered by an existing method, Prebid SDK Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the OpenRTB structure – it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server.

There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed.

Here’s how to specify cross-impression data:

//global invocation
adUnitConfiguration?.ortbConfig = "{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}"

To merge impression-level data, use the adUnit object:

//ad unit / impression-level
adUnit?.ortbConfig = "{\"ext\":{\"gpid\":\"abc123\"}}"

Notes:

• App and User first party data should use the functions defined for those purposes
• See the Prebid Server auction endpoint reference for more information about how it will process incoming fields.

Further Reading

• Prebid Mobile Overview
• Prebid SDK Android integration