Get started with Android Header Bidder SDK for GAM

The Adapex header bidder SDK lets publishers leverage the power of our wrapper to request multiple programmatic bids for their mobile in-app inventory.  The Adapex header bidder sends an initial ad call that goes to one or more partners requesting bids for inclusion in the ad server’s inventory allocation process.

  1. Our header bidder SDK calls the wrapper before requesting an ad from the primary AdServer SDK.
  2. Programmatic buyers get first look at the inventory, submit a bid price, then the wrapper conducts a server-side auction between bids from different partners configured by the publisher.
  3. Our header bidder includes the winning bid data (including bid eCPM and dealid), in the ad server call, which checks whether other buyers in the same priority tier can beat it. The impression is allocated to the highest yielding buyer while respecting other publisher controls that may have been set up on the ad server
  4. If the Adapex header bidder wins the bid, the ad server returns the winning ad to the Adapex header bidder SDK.
  5. The header bidder renders any ad returned by the ad server.

You can also let winning bids compete with prices available from direct-sold ads by setting the header bidder SDK line items to same priority as your direct sold line items.

The Adapex header bidder SDK provides the following benefits:

All the demand sources bid at the same time, replacing the sequential preferential ordering

  • of buyers.
  • Advertisers have the chance to obtain the best ad inventory.
  • Publishers can potentially see up to a 50% monetization increase.

The SDK automatically declares the   com.google.android.gms.AD_ID permission and can access the Advertising ID whenever it’s available. To learn more about the   com.google.android.gms.AD_ID permission declaration, including how to disable it, see  this Google Advertising ID article .

Required dependencies

DEVELOPMENT ENVIRONMENT  Android Studio 3.2 or higher.

TARGET ENVIRONMENT  Android version 4.4 (API level 19) – Android version 12 (API level 31).

PUBLISHER/PLACEMENT DETAILS

Before starting the header bidder SDK integration with supported ads in your app, you must have the following details:

  • Publisher ID
  • Profile ID
  • Ad Unit Id
  • GAM Ad Unit Id

You can create a Profile using your own account. 

Questions?

Contact your Adapex Account Manager.

AD SERVER CONFIGURATION FOR WRAPPER AND SDK This step is required so the GAM ad server, based on the actual bid price, can allocate impressions to the winning partner

AD SERVER SDK You must integrate the Google Mobile Ads SDK (referred to as GAM, or its former abbreviation DFP, in this documentation), to work with the OpenWrap SDK.

Integrate the Google Mobile Ads SDK (GAM)

Before integrating the header bidder SDK, you must first integrate the Google Mobile Ads SDK into your app. The Adapex header bidder SDK is tested and certified with Google Mobile Ads SDK version v20.4.0 – v21.0.0.  If you need additional assistance, contact your Account Manager.

  1. Integrate GAM in your app by updating the allprojects section of your project-level  build.gradle file.

    Add repository dependency
    1
    2
    3
    4
    5
    allprojects {
       repositories {
          google() 
       }
    }
  2. Now update the dependencies section of your app-level build.gradle  as shown in the code block below.

  3. Add your Ad Manager app ID to your app’s AndroidManifest.xml file as a <meta-data> tag with the property, android:name="com.google.android.gms.ads.APPLICATION_ID". You’ll find the app ID in the Ad Manager UI. For android:value insert your Ad Manager app ID in quotes, similar to the example below. Learn more

Integrate Wrapper SDK

Integrate the Adapex header bidder SDK in your app by updating the Gradle and AndroidManifest.xml files to satisfy this wrapper SDK dependency: 

DoubleClick for Publishers (DFP) has been rebranded as Google Ad Manager (GAM), but you should continue to use DFP in your code.

  1. Add Adapex’s maven repository to the allprojects section of your project-level build.gradle file. 

    Add repository dependency
    1
    2
    3
    4
    5
    6
    7
    allprojects {
       repositories {
          maven {
            url 'https://repo.adapex.com/artifactory/public-repos'
          }
       }
    }

    At this point, your allprojects section of your project-level  build.gradle should look similar to this:

    Project-level build.gradle
    1
    2
    3
    4
    5
    6
    7
    8
    allprojects {
       repositories {
          google()
          maven {  
            url 'https://repo.adapex.com/artifactory/public-repos'
          }
       }
    }
  2. Now update the dependencies section of your app-level build.gradle with the wrapper SDK and GAM handlers. Adapex’s event handler for GAM is essential as it  makes the ad server call using GAM SDK APIs.

    Add lib dependency
    1
    2
    3
    4
    5
    6
    dependencies{
        // To integrate Header Bidder SDK
        implementation 'com.adapex.sdk:wrapper:2.6.1'
        // To integrate GAM event handler
        implementation 'com.adapex.sdk:wrapper-eventhandler-dfp:2.8.0'
    }

    At this point, the dependencies section of your app-level build.gradle should look similar to this:

    App-level build.gradle
    1
    2
    3
    4
    5
    6
    dependencies{
        // Your app dependencies
        implementation 'com.google.android.gms:play-services-ads:21.0.0'
        implementation 'com.adapex.sdk:wrapper:2.6.1'
        implementation 'com.adapex.sdk:wrapper-eventhandler-dfp:2.8.0'
    }
  3. Save your Gradle file and perform Gradle sync.

Add permissions to AndroidManifest.xml file

Now that you’ve satisfied the required dependencies, it’s time to update permissions in your AndroidManifest.xml file. Android OpenWrap SDK requires only two mandatory permissions:

PERMISSION
DESCRIPTION
MANDATORY
Internet Required to access the Internet for ad-content download. Yes
Network State Required to access the network for ad request parameter setting. Yes
Coarse Location

If your app targets Android 12 and you request the ACCESS_FINE_LOCATION permission, you must also request the ACCESS_COARSE_LOCATION permission. You must include both permissions in a single runtime request. If you try to request only ACCESS_FINE_LOCATION, the system ignores the request and logs the following error message in LogCat: ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

See, User can grant only approximate location.

No
Fine Location

Required if you want the SDK to fetch the device’s precise location.

If your app targets Android 12 and you request the ACCESS_FINE_LOCATION permission, you must also request the ACCESS_COARSE_LOCATION permission.
 
You must include both permissions in a single runtime request. If you try to request only ACCESS_FINE_LOCATION, the system ignores the request and logs this error message in LogCat:
 
ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.
 
For more information, see Android’s User can grant only approximate location.

No
External Storage Required to access SD card photo and file storage to support MRAID features. No
Read Phone State It is required from API level 30 onwards, to get the cellular connection type (3G/4G/etc). If this permission is not granted then Ad request parameter ‘device.connectiontype’ will be sent as ‘3’ i.e. ‘Cellular Network – Unknown’. No

The following code snippet adds necessary permissions to your app’s AndroidManifest.xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<manifest>
    <!--
     Mandatory permission for Adapex SDK
    -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission
android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <!--
      Optional permission for Adapex SDK
    -->
    <uses-permission
android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission
android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <!--
      Ask this permission to user (at runtime from code) only for API 30+
    -->
    <uses-permission
android:name="android.permission.READ_PHONE_STATE"/>
</manifest>

Network security configuration

The Adapex header bidder SDK defaults to secure ad calls and delivers only secure ads. If you configure the header bidder SDK to serve non-secure ads, as described in Advanced topics > Configure SSL , you should opt-out of cleartext traffic as  Android 9.0 (API 28) blocks cleartext (non-HTTPS) traffic by default , which prevents ads from rendering. To resolve this in apps running on Android 9.0 or above, include a network security config file that allowlists cleartext traffic and allows HTTP ads to render.

  1. Create the res/xml/ network_security_config.xml resource file in your app, then add the following XML:

    <?xml version="1.0" encoding="utf-8"?>
     <network-security-config>
        <base-config cleartextTrafficPermitted="true">
            <trust-anchors>
                <certificates src="system"/>
            </trust-anchors>
        </base-config>    
    </network-security-config>

Update the <application> tag of your app’s AndroidManifest.xml file to match the following example:

<manifest>
    <application
       android:networkSecurityConfig="@xml/network_security_config">
    </application>
</manifest>

Supported ad formats

Now that you’ve integrated the Adapex header bidder Android SDK, you’re ready to begin implementing ads in your app. The header bidder Android SDK currently supports the following ad formats:

Banner:

Mobile banner ads usually appear as a short strip spanning the width of the app page or screen, positioned above or below the app content. Banner ads can be static or animated images, any mobile-compatible rich media ad format, or in-banner video.

Native and Banner:

Native ads are native assets rendered via an app’s native UI components to provide a consistent visual design. Though the header bidder SDK doesn’t support native ads separately, you can combine native and banner requests to support native inventory through the SDK’s header bidding feature.

Interstitial:

Mobile interstitial ads fill the screen or page and require the user to dismiss the ad before they can view/access the app’s main content. Interstitial ads also support static or animated full-screen images, any mobile-compatible rich media ad format, or full-screen video.

Rewarded:

Mobile rewarded ads fill the screen or page and require the user to dismiss the ad before they can view/access the app’s main content. Rewarded ads support only full-screen video ad formats. Once video playback completes the user receives in-app rewards.

 

WHAT OUR CLIENTS SAY

Satisfied Clients