Get started with Android OpenWrap SDK for MoPub

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 the supported ads in your app, you must have the following details:

  • Publisher ID
  • OpenWrap Profile ID
  • OpenWrap Ad Unit Id
  • MoPub 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 MoPub ad server, based on actual bid price, can allocate impressions to the winning partner. See MoPub ad server setup.
Ad Server SDKYou must Integrate MoPub SDK, to work with the OpenWrap SDK.

If your app uses Android support library

follow the instructions provided on the AndroidX Migration page.

Integrate MoPub SDK

Before you start integrating the PubMatic OpenWrap SDK, you must integrate the MoPub SDK in your app. OpenWrap SDK is tested and certified with MoPub SDK versions 5.13.0 - 5.18.0For more details, see the  compatibility matrixIf you need to use any other MoPub SDK versions, please reach out to your PubMatic Account Manager.

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

    Add repository dependency
    allprojects {
        repositories {
            jcenter()
            // includes the MoPub SDK
            mavenCentral()
        }
    }
  2. Now update the dependencies section of your app-level build.gradle  as shown in the following code:

    Add lib dependency
    dependencies{
    	// For banners
        implementation('com.mopub:mopub-sdk-banner:5.18.0@aar') {
            transitive = true
        }
    
        // For interstitials
        implementation('com.mopub:mopub-sdk-fullscreen:5.18.0@aar') {
            transitive = true
        }
    }
  3. Update your app's  AndroidManifest.xml by registering the MoPub activity's as shown below to complete MoPub SDK integration.

    Update app AndroidManifest.xml
    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
        <application>
            <!---->
            <!-- MoPub's consent dialog -->
            <activity android:name="com.mopub.common.privacy.ConsentDialogActivity"
                android:configChanges="keyboardHidden|orientation|screenSize"/>
    
            <!-- All ad formats -->
            <activity android:name="com.mopub.common.MoPubBrowser"
                android:configChanges="keyboardHidden|orientation|screenSize"/>
            <activity android:name="com.mopub.mobileads.MraidVideoPlayerActivity"
                android:configChanges="keyboardHidden|orientation|screenSize"/>
    
            <!-- Interstitials -->
            <activity android:name="com.mopub.mobileads.MoPubActivity"
                android:configChanges="keyboardHidden|orientation|screenSize"/>
            <activity android:name="com.mopub.mobileads.MraidActivity"
                android:configChanges="keyboardHidden|orientation|screenSize"/>
    
    
        </application>
    </manifest>


Once you have integrated the MoPub SDK and have created an ad unit, you must initialize MoPub SDK before you send ad requests .    

Initialize MoPub SDK only once using any valid ad unit ID from your app. T
o initialize MoPub SDK, add the code below to your app's onCreate() 
Activity (or equivalent). See MoPub Initialization for more information.  

Java Kotlin

Integrate OpenWrap SDK

The next step is to integrate the PubMatic OpenWrap SDK and event handlers in your application. This is important because it makes the ad server call using MoPub SDK APIs.

To ensure you're using the correct OpenWrap handler for your target MoPub version, check the OpenWrap and MoPub version compatibility matrix below.

OpenWrap handler compatibility matrix

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

How read the martix

  • If you're using OW SDK v2.2.0 and want to use MoPub SDK v5.16.0 - 5.17.0, then use handler version 2.3.0 - 2.4.0.
  • If you're using OW SDK v1.9.0 and want to use MoPub SDK v5.13.0 - 5.15.0, then use handler version 1.4.0.
Compatible OW SDK version(s)Use OW handler versionCompatible MoPub SDK version(s)
2.1.0 - 2.3.02.3.0 - 2.4.0

5.16.0 - 5.18.0

2.0.0 - 2.0.12.2.05.16.0 - 5.17.0
2.0.0 - 2.0.12.1.05.13.0 - 5.15.0
1.9.01.4.05.13.0 - 5.15.0
1.8.3 - 1.8.41.3.1 - 2.0.05.13.0 - 5.15.0

Integrate the OpenWrap SDK in your app by updating the Gradle and AndroidManifest.xml files to satisfy this OpenWrap SDK dependency:

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

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

    Add lib dependency
    dependencies{
    	// To integrate OpenWrap SDK
    	implementation 'com.pubmatic.sdk:openwrap:2.3.0'
    	// To integrate MoPub Event Handler
        implementation 'com.pubmatic.sdk:openwrap-eventhandler-mopub:2.4.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
    	// For MoPub banners
        implementation('com.mopub:mopub-sdk-banner:5.18.0@aar') {
            transitive = true
        }
    
        // For MoPub interstitials
        implementation('com.mopub:mopub-sdk-fullscreen:5.18.0@aar') {
            transitive = true
        }
    
    
    	// To integrate OpenWrap SDK
    	implementation 'com.pubmatic.sdk:openwrap:2.3.0'
    
    	// To integrate MoPub Event Handler
        implementation 'com.pubmatic.sdk:openwrap-eventhandler-mopub:2.4.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 non-secure 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>
  2. 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.

Setup MoPub ad server

Before you begin setting up banner and interstitial ads in your app integration, first setup MoPub ad server to work with OpenWrap SDK.

Table of Contents

« About Android OpenWrap SDK

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