Integration for Android

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 Maven or by cloning the repo and using our included script to build the SDK.

• SDK Integration
  • Maven
  • Build framework from source
• Add SDK
  • Set Prebid Server
  • Initialize SDK
  • Check compatibility with your GMA SDK
• Updating your Android manifest
• Set Targeting Parameters
• Supported Android versions
• Setup SDK
• Integrate Ad Units
  • Test configs

SDK Integration

Maven

If you are not familar with using Maven for build management visit the Maven website.

To include the Prebid Mobile SDK simply add this line to your gradle dependencies to get the latest stable release:

dependencies {
    ////
    
    // Prebid SDK
    implementation 'org.prebid:prebid-mobile-sdk:2.0.4'
}

Build framework from source

After cloning the repo, use Terminal or another command line tool to change to the root directory and run:

scripts/buildPrebidMobile.sh

This will output the PrebidMobile framework for Android.

Add SDK

Set Prebid Server

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

PrebidMobile.setPrebidServerAccountId(YOUR_ACCOUNT_ID)
PrebidMobile.setPrebidServerHost(Host.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.

PrebidMobile.setPrebidServerHost(Host.createCustomHost(PREBID_SERVER_AUCTION_ENDPOINT))

Initialize SDK

Once you set the account ID and the Prebid Server host, you should initialize the Prebid SDK. Use the following initialization for Prebid SDK:

PrebidMobile.initializeSdk(applicationContext) { status ->
    if (status == InitializationStatus.SUCCEEDED) {
        Log.d(TAG, "SDK initialized successfully!")
    } else if (status == InitializationStatus.SERVER_STATUS_WARNING) {
        Log.e(TAG, "Prebid Server status checking failed: $status\n${status.description}")
    }
    else {
        Log.e(TAG, "SDK initialization error: $status\n${status.description}")
    }
}

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:

PrebidMobile.setCustomStatusEndpoint(PREBID_SERVER_STATUS_ENDPOINT)

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

Check compatibility with your GMA SDK

If you integrate Prebid Mobile with GMA SDK, use the following method, which checks the compatibility of Prebid SDK with GMA SDK used in the app:

PrebidMobile.checkGoogleMobileAdsCompatibility(MobileAds.getVersion().toString())

Check the log messages of the app. If the provided GMA SDK version is not verified for compatibility, the Prebid SDK will log a warning.

Updating your Android manifest

Before you start, you need to integrate the SDK by updating your Android manifest.

Open your AndroidManifest.xml and add the following permissions and activity declarations according to the bundle you are integrating.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Notes:

• ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION will automatically allow the device to send user location for targeting, which can help increase revenue by increasing the value of impressions to buyers.
• WRITE_EXTERNAL_STORAGE is optional and only required for MRAID 2.0 storePicture ads.

For banner and interstitial ads only, include the following custom activities (even though you won’t instantiate them directly). This is not necessary for video interstitial ads.

Custom Activities:

<activity
    android:name="org.prebid.mobile.rendering.views.browser.AdBrowserActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:windowSoftInputMode="adjustPan|stateHidden"
    android:launchMode="singleTop"/>  

NOTE

Interstitial ads are implemented in a dialog. For proper interstitial workflow it is recommended to use a separate Activity with configChanges attribute specified to avoid any issues which may occur on orientation change. See above example with configChanges attribute.

Add this tag to your <application> to use Google Play Services:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />  

Set Targeting Parameters

Targeting parameters enable you to define the target audience for the bid request. Prebid Mobile supports the following global targeting parameters. These targeting parameters are set only once and apply to all Prebid Mobile ad units. They do not change for a given user session.

View the full list of targeting parameters.

Supported Android versions

Prebid supports the following versions by release:

• Prebid SDK version 1.0 or 1.1 supports Android 16+
• Prebid SDK version 1.1.1+ supports Android 19+
• Prebid SDK version 2.0.0+ supporst Android 16+

Setup SDK

Apply global settings with the PrebidMobile object.

AccountId

String containing the Prebid Server account ID.

PrebidMobile.setPrebidServerAccountId(YOUR_ACCOUNT_ID)
var pbsAccountId = PrebidMobile.getPrebidServerAccountId()

Host

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

PrebidMobile.setPrebidServerHost(Host.RUBICON);

//or set a custom host
Host.CUSTOM.setHostUrl("https://prebid-server.bidder.com/");
PrebidMobile.setPrebidServerHost(Host.CUSTOM);

Timeout

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.

PrebidMobile.setTimeoutMillis(3000)

var timeout = PrebidMobile.getTimeoutMillis()

ShareGeoLocation

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.

PrebidMobile.setShareGeoLocation(true)

var isShareLocation = PrebidMobile.isShareGeoLocation()

CustomHeaders

The following methods enables the customization of the HTTP call to the Prebid server:

var headers = HashMap<String, String> ()
headers.put("custom-header-1", "prebid-in-action")

PrebidMobile.setCustomHeaders(headers)
        
headers = PrebidMobile.getCustomHeaders()

Auction Response

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.

PrebidMobile.setStoredAuctionResponse("response-prebid-banner-320-50")

StoredBidResponses

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.

PrebidMobile.addStoredBidResponse("appnexus", "221144");
PrebidMobile.addStoredBidResponse("rubicon", "221155");

To stop sending stored bid response signals use the following method:

void clearStoredBidResponses()

Debug

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.

PrebidMobile.setPbsDebug(true)

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.