Get started with Android OpenWrap SDK for GAM


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

High-level process overview

  1. OpenWrap SDK calls OpenWrap before requesting an ad from the primary AdServer SDK.
  2. Programmatic buyers get first look at the inventory, submit a bid price, then OpenWrap conducts a server-side auction between bids from different OpenWrap partners configured by the publisher.
  3. OpenWrap 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 OpenWrap wins the bid, the ad server returns the winning ad to OpenWrap SDK.
  5. OpenWrap 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 OpenWrap SDK line items to same priority as your direct sold line items.

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

Required dependencies

Development environment 

Android Studio 3.2 or higher.

Target environment 

Android minimum API level 19; Android Version 4.4 (Kitkat), or higher.

Publisher/placement details

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

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

You can use PubMatic test profiles to test during SDK integration.

OR

You can create an OpenWrap Profile using your own account. To learn more about OpenWrap profile creation and management see,  OpenWrap Mobile In-App Support .

Questions?

Contact your PubMatic Account Manager.
Ad Server configuration for OpenWrap and SDKThis step is required so the GAM ad server, based on actual bid price, can allocate impressions to the winning partner. See GAM Ad Server Configuration (for OpenWrap and in-app SDK) .
Ad Server SDKYou 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.

If your app uses Android support library:

follow the instructions provided on the AndroidX Migration page.

Integrate the Google Mobile Ads SDK (GAM)

Before you start integrating the PubMatic OpenWrap SDK, you must integrate the Google Mobile Ads SDK in your app. OpenWrap SDK is tested and certified with Google Mobile Ads SDK version 20.0.0 - 20.3.0For more details, see the  compatibility matrix . If you need additional assistance, contact your PubMatic Account Manager.

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

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

    Add lib dependency
    dependencies{
    	implementation 'com.google.android.gms:play-services-ads:20.3.0'
    }
  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 own Ad Manager app ID in quotes, similar to the example below. Learn more

    Update app AndroidManifest.xml
    <application>
        <!-- Sample Ad Manager app ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
    </application>


Integrate OpenWrap SDK

If you are migrating from a version of OpenWrap SDK earlier than 2.2.0:

To ensure you're using the appropriate handler for your project's requirements, check the OpenWrap and GAM version compatibility matrix below.

OpenWrap handler compatibility matrix

The OpenWrap handler for GAM is the bridge between OpenWrap SDK and an Ad Server SDK. Find the appropriate OpenWrap handler for your target GAM version from the table below.

How read the matrix:

  • If you're using OpenWrap SDK v2.3.0 and want to use GAM SDK v20.0.0 - 20.3.0, then use handler version 2.5.0.
  • If you're using OpenWrap SDK 1.9.0 and want to use GAM SDK v19.5.0-19.8.0, then use handler version 1.4.0.
Compatible OW SDK version(s)Use OW handler versionCompatible GAM SDK version(s)
2.3.02.5.020.0.0 - 20.3.0
2.2.02.4.020.0.0 – 20.2.0
2.1.02.3.0

20.0.0 – 20.2.0

1.9.01.4.019.5.0 – 19.8.0

Integrate OpenWrap SDK in your app by updating the Gradle and AndroidManifest.xml files to satisfy this OpenWrap 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 PubMatic's maven repository to the allprojects section of your project-level build.gradle file. 

    Add repository dependency
    allprojects {
       repositories {
          maven {
        	url 'https://repo.pubmatic.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
    allprojects {
       repositories {
    	  google()
          maven {	
        	url 'https://repo.pubmatic.com/artifactory/public-repos'
    	  }	
       }
    }
  2. Now update the dependencies section of your app-level build.gradle with OpenWrap SDK and GAM handlers. The PubMatic's event handler for GAM is important as it makes the ad server call using GAM SDK APIs.

    Add lib dependency
    dependencies{
    	// To integrate OpenWrap SDK
    	implementation 'com.pubmatic.sdk:openwrap:2.3.0'
    	// To integrate GAM event handler
        implementation 'com.pubmatic.sdk:openwrap-eventhandler-dfp:2.5.0'
    }

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

    App-level build.gradle
    dependencies{
        // Your app dependencies
    	implementation 'com.google.android.gms:play-services-ads:20.3.0'
    	implementation 'com.pubmatic.sdk:openwrap:2.3.0'
    	implementation 'com.pubmatic.sdk:openwrap-eventhandler-dfp:2.5.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:

PermissionDescriptionMandatory
InternetRequired to access the Internet for ad-content download.Yes
Network StateRequired to access the network for ad request parameter setting.Yes
Fine LocationRequired if you want the SDK to fetch the device location.No
External StorageRequired to access SD card photo and file storage to support MRAID features.No
Read Phone StateIt 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:

Update app AndroidManifest.xml
<manifest>
   <!--
     Mandatory permission for OpenWrap SDK
   -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <!--
     Optional permission for OpenWrap SDK
   -->
    <uses-permission android:name="android.permission.ACCESS_FINE_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

OpenWrap SDK defaults to secure ad calls and delivers only secure ads. If you configure OpenWrap 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>

Sample apps

For more integration details, have a look at the OpenWrap SDK sample apps.

Supported ad formats

Now that you've integrated the OpenWrap Android SDK, you're ready to begin implementing ads in your app. The OpenWrap Android SDK currently supports 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 OpenWrap 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.

Table of Contents

« About Android OpenWrap SDK

Do you have feedback on this document? Let us know: email us.