Prebid SDK Global Parameters - iOS

• How to Read this Guide
• Prebid Class Global Properties and Methods
  • Prebid Class Global Properties
  • Prebid Class Global Methods
    • setCustomPrebidServerUrl()
    • addStoredBidResponse()
    • clearStoredBidResponses()
    • addCustomHeader()
    • clearCustomHeaders()
• Consent Management Parameters
  • iOS App Tracking Transparency
  • 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
  • Banner API Code
• First Party Data
  • User FPD
  • Inventory FPD
  • Controlling Bidder Access to FPD
• User Identity
  • Storing IDs in a Property
  • Storing IDs in Local Storage
  • IDs that Require Additional SDKs
    • Unified ID 2.0 (UID2)
• Targeting Class Properties and Methods
  • Targeting Class Properties
  • Targeting Class Methods
• Arbitrary OpenRTB
• Further Reading

How to Read this Guide

This page documents various global parameters you can set on the Prebid SDK for iOS. 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 Class 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.prebidServerAccountId="12345"
Prebid.shared.customStatusEndpoint="https://pbs.example.com/v2/status"

Prebid Class Global Methods

setCustomPrebidServerUrl()

Defines which Prebid Server to connect to. See the initialization page for iOS.

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:

func addStoredBidResponse(bidder: String, responseId: String)

Parameters:

clearStoredBidResponses()

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

Signature:

func clearStoredBidResponses()

Parameters: none.

addCustomHeader()

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

Signature:

func addCustomHeader(name: String, value: String)

Parameters:

clearCustomHeaders()

Allows you to clear any custom headers you have previously set.

Signature:

func clearCustomHeaders()

Parameters: none

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.

iOS App Tracking Transparency

You should follow Apple’s Guidelines on implementing App Tracking Transparency. The Prebid SDK automatically sends ATT signals, so no Prebid-specific work is required.

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 UserDefaults. 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:

Swift:

Targeting.shared.subjectToGDPR = false
Targeting.shared.setSubjectToGDPR(false)

To provide the consent string:

Swift:

Targeting.shared.gdprConsentString = "BOMyQRvOMyQRvABABBAAABAAAAAAEA"

To set the purpose consent:

Swift:

Targeting.shared.purposeConsents = "100000000000000000000000"

Related functions: getSubjectToGDPR(), getDeviceAccessConsent(), getDeviceAccessConsentObjc, getPurposeConsent(), isAllowedAccessDeviceData().

Getting Consent Values from the CMP

Prebid SDK reads the values for the following keys from the UserDefaults 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 the UserDefaults 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:

Swift:

Targeting.shared.subjectToCOPPA = 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 UserDefaults. 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.

Targeting.shared.omidPartnerName = "Google"

Partner Version

The OMSDK version number for the integration partner.

Targeting.shared.omidPartnerVersion = "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]

This translates in OpenRTB to imp[].banner.api=7.

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 or Contextual 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.

func setLatitude(latitude: Double, longitude: Double)

func addUserData(key: String, value: String)

func updateUserData(key: String, value: Set<String>)

func removeUserData(forKey: String)

func clearUserData()

func addUserKeyword(_ newElement: String)

func addUserKeywords(_ newElements: Set<String>)

func removeUserKeyword(_ element: String)

func clearUserKeywords()

func getUserKeywords()

Example:

Targeting.shared.addUserData(key: "globalUserDataKey1", value: "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.

Related functions: setYearOfBirth(), getYearOfBirth() and clearYearOfBirth().

Inventory FPD

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

func addAppExtData(key: String, value: String)

func updateAppExtData(key: String, value: Set<String>)

func removeAppExtData(for key: String)

func clearAppExtData()

func getAppExtData()

func addAppKeyword(_ newElement: String)

func addAppKeywords(_ newElements: Set<String>)

func removeAppKeyword(_ element: String)

func clearAppKeywords()

func getAppKeywords()

Example:

Targeting.shared.addAppExtData((key: "globalContextDataKey1", value: "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:

func addBidderToAccessControlList(_ bidderName: String)

func removeBidderFromAccessControlList(_ bidderName: String)

func clearAccessControlList()

Example:

Targeting.shared.addBidderToAccessControlList(Prebid.bidderNameRubiconProject)

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 User ID 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”.

Storing IDs in a Property

Prebid SDK supports passing an array of EIDs at auction time in the Prebid global field externalUserIdArray. Setting the externalUserIdArray object once per user session is sufficient unless one of the values changes.

public var externalUserIdArray = [ExternalUserId]()

Examples

// User Id from External Third Party Sources
var externalUserIdArray = [ExternalUserId]()

externalUserIdArray.append(ExternalUserId(source: "adserver.org", identifier: "111111111111", ext: ["rtiPartner" : "TDID"]))
externalUserIdArray.append(ExternalUserId(source: "netid.de", identifier: "999888777"))
externalUserIdArray.append(ExternalUserId(source: "criteo.com", identifier: "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N"))
externalUserIdArray.append(ExternalUserId(source: "liveramp.com", identifier: "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg"))
externalUserIdArray.append(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1))

Prebid.shared.externalUserIdArray = externalUserIdArray

setExternalUserIds(List<ExternalUserId> externalUserIds)

Storing IDs in Local Storage

Prebid SDK provides a local storage interface to set, retrieve, or update an array of user IDs with associated identity vendor details. It will then retrieve and pass these User IDs to Prebid Server on each auction, even on the next user session.

Prebid SDK Provides several functions to handle User ID details within the local storage:

public func storeExternalUserId(_ externalUserId: ExternalUserId)

public func fetchStoredExternalUserIds() -> [ExternalUserId]?

public func fetchStoredExternalUserId(_ source : String) -> ExternalUserId?

public func removeStoredExternalUserId(_ source : String)

public func removeStoredExternalUserIds()

Examples

//Set External User ID
Targeting.shared.storeExternalUserId(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1))

//Get External User ID
let externalUserIdSharedId = Targeting.shared.fetchStoredExternalUserId("sharedid.org")

//Get All External User IDs
let externalUserIdsArray = Targeting.shared.fetchStoredExternalUserIds()

//Remove External UserID
Targeting.shared.removeStoredExternalUserId("sharedid.org")

//Remove All External UserID
Targeting.shared.removeStoredExternalUserIds()

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 iOS into Prebid’s external user’s ID list.

App developers are not required to manually call Prebid.shared.externalUserIdArray = latestExternalUserIdArray as the native library will do so automatically

Note:

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

Targeting Class Properties and Methods

There are several other fields app developers may want to set to give bidders additional information about the auction.

Targeting Class Properties

Note that several of the properties noted here are also mentioned above for other use cases, e.g. subjectToCOPPA. All properties of the ‘Targeting’ class are listed here.

Targeting Class Methods

All of the targeting class methods have been mentioned above in the context of First Party Data section above.

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
adUnitConfig.setOrtbConfig("{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}")

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

//ad unit / impression-level
adUnit.setOrtbConfig("{\"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 iOS integration