Getting Started - PubMatic/android-openwrap-ima-sample GitHub Wiki

This sample application illustrates how to enable OpenWrap header bidding for an in-stream video ad in an Android app.

High-level process overview

OTT_Workflow

  1. The sample app sends the video ad request to the OpenWrap server.
  2. OpenWrap sends the ad call to the OpenWrap partners that are configured by the publisher.
  3. OpenWrap returns the winning ad to the application.
  4. The application prepares the GAM AdTag URL with winning bid targeting attributes.
  5. IMA SDK makes an Ad request using prepared AdTag URL in step 4.
  6. GAM performs an auction between OpenWrap Bid and GAM campaigns.
  7. IMA SDK renders the winning video ad.

Ad Server configuration for OpenWrap

This step is required so the GAM ad server can allocate impressions to the winning partner based on the actual bid price.

Please work with your PubMatic contact to complete this step.

Import the sample application

  1. Download source code using this repository.
  2. Open the project in Android Studio and run the application.

Note: You can reuse the OpenWrap Module in your application from this source code. This module uses the OpenWrap Video API to fetch video ads from the OpenWrap server.

External dependency

Below are the third-party libraries added in OpenWrap module:

1. Google Play Services for Advertising ID

OpenWrap Module of this application has the below dependency of Google Play Services to get the Advertising Id and LMT state.

i. Added on build.gradle.

dependencies {
    ...
    // For getting advertising ID
    implementation 'com.google.android.gms:play-services-ads:19.2.0'
}

ii. Required below meta-data in manifest.xml.

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

2. Volley library for networking.

dependencies {
    ...
    implementation 'com.android.volley:volley:1.1.1'
}

Integration steps

The following steps describe how the sample application has been integrated with OpenWrap Video and IMA SDK.

Step 1: Getting Bids from OpenWrap.

This application uses various classes implemented in OpenWrap Module, which is used to fetch the video bids using OpenWrap Video API and pass the bid targeting to IMA SDK to perform the auction and render the video ad.

Note: App inventory transparency is very important to buyers. You must set the Google Play storeURL of your app before you request an ad. The Store URL should be the URL where users can download your app from the Google Play Store.

The integration in Activity looks like:

// Inside activity

// Class variables: Point of interaction with OpenWrap. It is responsible to request Ad to OpenWrap and pass on the response to Activity.
private ImaAdsLoader adsLoader;
private POWAdsLoader owAdsLoader;

// Player to render the content video on screen.
private PlayerView playerView;
private SimpleExoPlayer player;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    // Initialize player view
    playerView = findViewById(R.id.player_view);

    // Update the GAM URL with the required values (for example, ad unit ID and ad size).
    gamAdsUrl = getGAMAdTagUrl();

    // Initialise OpenWrap Ads Loader
    owAdsLoader = new POWAdsLoader(this);

    // Create OpenWrap request with valid params
    POWAdRequest adRequest = new POWAdRequest(Constants.PUB_ID, Constants.PROFILE_ID,
            Constants.AD_UNIT_ID, AD_SIZE);

    // Set Application details
    // App inventory transparency is very important to the buyers, so you must set the Google Play storeURL for your app before you make an ad request. 
    POWConfiguration configuration = POWConfiguration.getInstance();
    POWApplicationInfo applicationInfo = new POWApplicationInfo(this);
    applicationInfo.setStoreURL("https://play.google.com/store/apps/details?id=com.example.lite&hl=en_IN");
    configuration.setAppInfo(applicationInfo);

    // Set listener to get loader event callbacks
    owAdsLoader.setAdsLoaderListener(this);

    // Load OpenWrap ad
    owAdsLoader.loadAd(adRequest);
}

// Method to get GAM request URL for IMA SDK
private String getGAMAdTagUrl() {
       // The GAM ad tag url will be like, "https://pubads.g.doubleclick.net/gampad/live/ads?iu=<GAM_AD_UNIT_ID>"
       // + "&description_url=http://pubmatic.com/&tfcd=0&npa=0&sz=<GAM_AD_SIZE>&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s";
    return "<#GAM_Ad_Tag_URL#>";
}

See Supported Parameters and Testing for details on passing user-specific, application-specific parameters, CCPA, GDPR, etc. to OpenWrap.

Step 2: Prepare GAM URL with OpenWrap bid targeting

  1. Once the OpenWrap bid is received in adsLoader.onAdReceived() callback method, get the targeting information from POWAdResponse object.
  2. Convert this targeting in the form of JSONObject using method response.getTargeting()
  3. Encode the targeting info string using the method POWUtil.generateEncodedQueryParams(), then set as a value to gamAdsUrl query parameter of IMA ad tag URL and pass this newly formed IMA ad tag URL to IMA SDK to request ad.
@Override
public void onAdReceived(@NonNull POWAdResponse response) {
    JSONObject targetingJson = response.getTargeting();
    if (targetingJson != null) {
        this.gamAdsUrl = this.gamAdsUrl + "&cust_params=" + POWUtil.generateEncodedQueryParams(targetingJson);
    }
    //initialize IMA AdLoader using modified gamAdsUrl
    initializeAdLoader(this.gamAdsUrl);
}

@Override
public void onAdFailed(int errorCode, @Nullable String errorMsg) {
    //initialize IMA AdLoader using gamAdsUrl
    initializeAdLoader(this.gamAdsUrl);
}

Step 3: Requesting GAM Ads

Once GAM AdTagURI is prepared with bids targeting from OpenWrap, continue with the IMA SDK initialization. For example:

// Create an AdsLoader with the ad tag URL.
adsLoader = new ImaAdsLoader(this.getApplicationContext(), Uri.parse(this.gamAdsUrl));
...

Supported Parameters and Testing

See Supported Parameters and Testing for details on passing user-specific, application-specific parameters, CCPA, GDPR, etc. to OpenWrap.