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
  • Point to a Prebid Server
    • Account Settings ID
  • Initialize SDK
• 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

Point to a Prebid Server

Once you have a Prebid Server, you will add ‘account’ info to the Prebid Mobile. For example, if you’re using the AppNexus Prebid Server:

Prebid.shared.prebidServerAccountId = YOUR_ACCOUNT_ID
Prebid.shared.prebidServerHost = .Appnexus

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:

adUnitConfig.setOrtbConfig = "{\"ext\":{\"prebid\":{\"storedrequest\": {\"id\":\"account-settings-id\"}}}}"

Initialize SDK

Once you set the account ID and the Prebid Server host, you should initialize the Prebid SDK. There are several options for how to do it.

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:

Prebid.initializeSDK(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(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 { status, error in
    // ....
}

During the initialization, SDK creates internal classes and performs the health check request to the /status endpoint. If you use a custom PBS host you should provide a custom status endpoint as well:

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.

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.

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

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

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

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