Prebid SDK Integration for iOS

Get started with Prebid Mobile by creating a Prebid Server account. Once your account is set up include the Prebid Mobile SDK in your app by either using dependencies managers or by cloning the repo and using our included script to build the SDK.

• SDK Integration
  • Cocoapods
  • Carthage
  • XCFramework
  • Swift PM
  • Build framework from source
• Add the Prebid SDK
  • Prebid Server Account ID
  • Point to a Prebid Server
    • Account Settings ID
  • Initialize SDK
    • Handling Tracking Domains
• Set Global Parameters
• Setup SDK
  • Properties
  • Methods
  • Server Side Configuration
• Integrate Ad Units
  • Test configs

SDK Integration

Cocoapods

If you are not familiar with using Cocoapods for dependency management, visit their getting started page. Once you have your Podfile setup, include the following:

target 'MyAmazingApp' do
    pod 'PrebidMobile'
end

Now run pod install to add the Prebid SDK to project dependencies.

Carthage

If you are not familiar with the Carthage package builder, please refer to the project github page for more details.

1. Install Carthage
2. Add github "prebid/prebid-mobile-ios" == 2.0.4-carthage to your Cartfile.
3. Run carthage update.
4. Drag PrebidMobile.xcframework from Carthage/Build to General -> Linked Frameworks and Libraries

XCFramework

1. Clone the project and run script scripts/buildPrebidMobile.sh
2. Drag PrebidMobile.xcframework from generated/output directory into your project. Make sure “Copy items if needed” is selected.
3. Go to your Xcode project’s General -> Frameworks, Libraries, and Embedded Content settings. Use Embed & Sign for dynamic and Do Not Embed for static linking

Swift PM

SPM isn’t supported for Prebid SDK 2.0.0 and higher (details).

The next guide is applicable to 1.x versions of the SDK.

If you are not familiar with the Swift Package Manager, please refer to the project github page for more details.

1. Add Prebid dependency File -> Swift Packages -> Add Package Dependency...
2. Select desired version, branch or commit
3. Select Prebid module

4. Build the specific schema CarthageBuild.sh

   Variant 1

   • Run CarthageBuild.sh script from Cartfile folder. The path should be: .../Carthage/Checkouts/prebid-mobile-ios/scripts/CarthageBuild.sh
   • Enter Schema name (PrebidMobile or PrebidMobileCore)
     • If you run CarthageBuild.sh and see Permission denied use: chmod +x <path_to_CarthageBuild.sh>

   Variant 2

   • Open PrebidMobile.xcodeproj at .../Carthage/Checkouts/prebid-mobile-ios/PrebidMobile.xcodeproj using Xcode
   • Manage Schemes -> Check Shared checkbox for a necessary schema
   • run carthage build prebid-mobile-ios
5. Integrate the binary into your project

You can find the schema name in the build PrebidSDK framework inside Info.plist with PrebidMobileName key

Build framework from source

Build Prebid Mobile from source code. After cloning the repo, use Terminal or another command line tool, change to the root directory and run:

scripts/buildPrebidMobile.sh

This will output the PrebidMobile.framework.

Add the Prebid SDK

Prebid Server Account ID

Once you have a Prebid Server, you will add ‘account’ info to the Prebid Mobile.

Prebid.shared.prebidServerAccountId = YOUR_ACCOUNT_ID

Point to a Prebid Server

Starting from PrebidMobile 3.0.0 the setCustomPrebidServer() method and the Host.Appnexus and Host.Rubicon enums have been removed. Please check the server URL in API changes and use PrebidMobile.initializeSdk (below) to set the Prebid Server URL.

In SDK 2.5 and before, if you’re using the AppNexus Prebid Server, you would do this:

Prebid.shared.prebidServerHost = .Appnexus

In SDK 2.5 and before, if you have opted to host your own Prebid Server solution, you will need to store the URL to the server in your app. Make sure that your URL points to the /openrtb2/auction endpoint.

try! Prebid.shared.setCustomPrebidServer(url: "https://prebidserver.example.com/openrtb2/auction")

This method throws an exception if the provided URL is invalid.

Account Settings ID

Each mobile app may have its own “account settings ID”. This is used to look up data in Prebid Server like timeout, targeting, and price granularity.

By default the Account Settings ID is set to be the same as the Account ID. i.e. the Prebid.shared.prebidServerAccountId property will set both values. If you want to define a different Account Settings ID as determined in conjunction with your Prebid Server team, use the arbitrary OpenRTB method like this:

Targeting.shared.setGlobalORTBConfig("{\"ext\":{\"prebid\":{\"storedrequest\": {\"id\":\"account-settings-id\"}}}}")

Initialize SDK

Once you set the account ID, you should initialize the Prebid SDK.

In SDK 3.0 and later, you need to enter a URL to your Prebid Server’s auction endpoint in your app. Get this URL from your Prebid Server provider. e.g. https://prebid-server.example.com/openrtb2/auction.

If you integrate Prebid Mobile with GMA SDK with version equal or higher than 10.7.0, use the following initializer, which checks the compatibility of Prebid SDK with GMA SDK used in the app:

• GMA SDK v12
• GMA SDK v11

Prebid.initializeSDK(PREBID_SERVER_URL, gadMobileAdsVersion: string(for: MobileAds.shared.versionNumber)) { status, error in
    switch status {
    case .succeeded:
        print("Prebid SDK successfully initialized")
    case .failed:
        if let error = error {
            print("An error occurred during Prebid SDK initialization: \(error.localizedDescription)")
        }
    case .serverStatusWarning:
        if let error = error {
            print("Prebid Server status checking failed: \(error.localizedDescription)")
        }
    default:
        break
    }            
}

Prebid.initializeSDK(PREBID_SERVER_URL, gadMobileAdsVersion: GADGetStringFromVersionNumber(GADMobileAds.sharedInstance().versionNumber) { status, error in
    switch status {
    case .succeeded:
        print("Prebid SDK successfully initialized")
    case .failed:
        if let error = error {
            print("An error occurred during Prebid SDK initialization: \(error.localizedDescription)")
        }
    case .serverStatusWarning:
        if let error = error {
            print("Prebid Server status checking failed: \(error.localizedDescription)")
        }
    default:
        break
    }            
}

If you integrate Prebid Mobile with GMA SDK with version lower than 10.7.0, use the following initializer:

Prebid.initializeSDK(PREBID_SERVER_URL, GADMobileAds.sharedInstance()) { status, error in
    switch status {
    case .succeeded:
        print("Prebid SDK successfully initialized")
    case .failed:
        if let error = error {
            print("An error occurred during Prebid SDK initialization: \(error.localizedDescription)")
        }
    case .serverStatusWarning:
        if let error = error {
            print("Prebid Server status checking failed: \(error.localizedDescription)")
        }
    default:
        break
    }
}

Check the log messages of the app. If the provided GMA SDK version is not verified for compatibility, the Prebid SDK informs about it.

For the No Ad Server scenario, use the following initialization:

Prebid.initializeSDK(PREBID_SERVER_URL) { status, error in
    // ....
}

All initialization methods may throw an exception if the provided server URL is invalid.

During the initialization, SDK creates internal classes and performs the health check request to the /status endpoint. If your Prebid Server provider has a non-standard path (anything other than /status), you should provide a the alternate status endpoint:

Prebid.shared.customStatusEndpoint = PREBID_SERVER_STATUS_ENDPOINT

If something goes wrong with the request, the status of the initialization callback will be .serverStatusWarning. It doesn’t affect an SDK flow and just informs you about the health check result.

Handling Tracking Domains

As part of Apple’s evolving privacy policies, SDKs that access user data in a way that could be used for tracking may be required to register tracking domains in the PrivacyInfo.xcprivacy file.

Currently, the Prebid Mobile SDK is not classified as one of these SDKs. But future changes from Apple or internal app review policies may prompt publishers to proactively register the Prebid Server (PBS) endpoint in the privacy manifest. To support this, the Prebid SDK is designed to accommodate both tracking and non-tracking PBS domains. Here are the Prebid recommendations:

• Include the relevant NSPrivacyCollectedDataTypes and define your primary Prebid Server domain in the NSPrivacyTrackingDomains array in your the PrivacyInfo.xcprivacy file to cover a potential “worst case” scenario. Read more about the PrivacyInfo.xcprivacy data here.
• You may choose to provide a secondary, privacy-mode PBS URL to the SDK. This secondary domain can be used when tracking is disallowed. Get this additional hostname from your Prebid Server host provider. Every initialization method contains optional parameter to define this privacy-safe PBS domain. Since these requests will have the limit ad tracking flag defined, Prebid Server will anonymize the requests.

You’re not required to use a secondary PBS domain – you can simply allow iOS to block PBS requests when the user opts out of tracking.

let trackingURL = "https://prebidserver.example.com/openrtb2/auction"
let nonTrackingURL = "https://prebidserver.example.nontracking.com/openrtb2/auction"
Prebid.initializeSDK(trackingURL, nonTrackingURL) { status, error in
    // ....
}

Depending on Apple’s domain monitoring mechanisms, even the privacy-mode domain could potentially be blocked. In such cases, the PBS provider may need to engage with Apple for resolution.

Set Global Parameters

There are several types of parameters app developers should consider providing to Prebid SDK:

• Values that control Prebid SDK behavior (timeout, etc)
• Privacy consent settings (TCF, GPP, COPPA, etc).
• First Party Data to help bidders understand the context and/or user better.

See the global parameters page for details.

Setup SDK

The Prebid class is a singleton that enables the user to apply global settings.

Properties

prebidServerAccountId: String containing the Prebid Server account ID.

prebidServerHost: String containing configuration your Prebid Server host with which Prebid SDK will communicate. Choose from the system-defined Prebid Server hosts or define your own custom Prebid Server host.

auctionSettingsId: Allows you to separate account from “auction settings”. This is used to set ext.prebid.storedrequest.id, otherwise prebidServerAccountId is taken by default. This allows each app to have different global parameters like timeout, price granularity, etc. Please work with your Prebid Server provider to determine what to enter here.

shareGeoLocation: Optional Bool, if this flag is True AND the app collects the user’s geographical location data, Prebid Mobile will send the user’s geographical location data to Prebid Server. If this flag is False OR the app does not collect the user’s geographical location data, Prebid Mobile will not populate any user geographical location information in the call to Prebid Server. The default setting is false.

logLevel: Optional level of logging to output in the console. Options are one of the following sorted by a verbosity of the log:

public static let debug = LogLevel(stringValue: "[💬]", rawValue: 0)
public static let verbose = LogLevel(stringValue: "[🔬]", rawValue: 1)
public static let info = LogLevel(stringValue: "[ℹ️]", rawValue: 2)
public static let warn = LogLevel(stringValue: "[⚠️]", rawValue: 3)
public static let error = LogLevel(stringValue: "[‼️]", rawValue: 4)
public static let severe = LogLevel(stringValue: "[🔥]", rawValue: 5)

timeoutMillis: The Prebid timeout (accessible to Prebid SDK 1.2+), set in milliseconds, will return control to the ad server SDK to fetch an ad once the expiration period is achieved. Because Prebid SDK solicits bids from Prebid Server in one payload, setting Prebid timeout too low can stymie all demand resulting in a potential negative revenue impact.

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

creativeFactoryTimeoutPreRenderContent: Controls how long video and interstitial creatives have to load before it is considered a failure.

storedAuctionResponse: Set as type string, stored auction responses signal Prebid Server to respond with a static response matching the storedAuctionResponse found in the Prebid Server Database, useful for debugging and integration testing. No bid requests will be sent to any bidders when a matching storedAuctionResponse is found. For more information on how stored auction responses work, refer to the written description on github issue 133.

pbsDebug: adds the debug flag (“test”:1) on the outbound http call to Prebid Server. The test:1 flag will signal to Prebid Server to emit the full resolved request (resolving any Stored Request IDs) as well as the full Bid Request and Bid Response to and from each bidder.

Methods

Stored Response

addStoredBidResponse: Function containing two properties:

• bidder: Bidder name as defined by Prebid Server bid adapter of type string.
• responseId: Configuration ID used in the Prebid Server Database to store static bid responses.

Stored Bid Responses are similar to Stored Auction Responses in that they signal to Prebid Server to respond with a static pre-defined response, except Stored Bid Responses is done at the bidder level, with bid requests sent out for any bidders not specified in the bidder parameter. For more information on how stored auction responses work, refer to the written description on github issue 133.

func addStoredBidResponse(bidder: String, responseId: String)

clearStoredBidResponses: Clears any stored bid responses.

func clearStoredBidResponses()

Custom headers

The following methods enable the customization of the HTTP call to the prebid server:

func addCustomHeader(name: String, value: String) 

func clearCustomHeaders() 

Server Side Configuration

You can pass some SDK configuration properties from PBS to the SDK using the ext.prebid.passthrough object, supported by Prebid Server, in the stored request.

For now Prebid SDK supports the following configuration properties:

• cftbanner - see the Prebid.creativeFactoryTimeout
• cftprerender - see the Prebid.creativeFactoryTimeoutPreRenderContent

An example of a stored request:

{
  "app": {
    "publisher": {
      "ext": {
        "prebid": {

        }
      }
    }
  },
  "ext": {
    "prebid": {
      "passthrough": [
        {
          "type": "prebidmobilesdk",
          "sdkconfiguration": {
            "cftbanner": 42,
            "cftprerender": 4242
          }
        }
      ]
    }
  },
  "test": 1
}

All values received in the passthrough of the bid response will be applied to the respective Prebid.* properties with the highest priority. After that, the SDK will utilize new values received in the bid response.

Examples

Starting from PrebidMobile 3.0.0 the prebidServerHost property and the setCustomPrebidServer method are removed. Use Prebid.initializeSDK instead. If you used Host.Appnexus or Host.Rubicon to set your host, you should check the server URL in API changes.

// Host (Removed in 3.0.0. Use `Prebid.initializeSDK` instead.)
Prebid.shared.prebidServerHost = .Rubicon
// or set a custom host (Removed in 3.0.0. Use `Prebid.initializeSDK` instead.)
Prebid.shared.prebidServerHost = PrebidHost.Custom
do {
    // Removed in 3.0.0. Use `Prebid.initializeSDK` instead.
    try Prebid.shared.setCustomPrebidServer(url: "https://prebid-server.customhost.com")
} catch {
    print(error)
}

// Account Id
Prebid.shared.prebidServerAccountId = "1234"

// Auction Settings Id (Optional)
Prebid.shared.auctionSettingsId = "7890"

// Geolocation
Prebid.shared.shareGeoLocation = true

// Log level data
Prebid.shared.logLevel = .verbose

// Set Prebid timeout in milliseconds
Prebid.shared.timeoutMillis = 3000

// Enable Prebid Server debug respones
Prebid.shared.pbsDebug = true

// Stored responses  can be one of storedAuction response or storedBidResponse
Prebid.shared.storedAuctionResponse = "111122223333"

//or
Prebid.shared.addStoredBidResponse(bidder: "appnexus", responseId: "221144")
Prebid.shared.addStoredBidResponse(bidder: "rubicon", responseId: "221155")

Integrate Ad Units

Follow the corresponding guide to integrate Prebid Mobile:

• GAM using Original API
• No Ad Server
• GAM using Rendering API
• AdMob
• AppLovin MAX

Test configs

In the table below, you can find Prebid’s test IDs that are used in the Demo Applications and that you can utilize for SDK integration validation.