Integrating Banner Ads

Document created by david.simerly on Oct 24, 2017Last modified by david.simerly on Apr 3, 2018
Version 15Show Document
  • View in full screen mode

PubMatic SDKs 

PubMatic Android SDK

Getting Started

➤  Integrating Banner Ads

Banner ads are images or text that appear on a portion of an app's screen. The ad stays on screen as the user interacts with the app. The ad can auto refresh periodically.

 

You'll need to follow the instructions in Getting Started before proceeding with the following integration steps. You'll also find a useful example integration in pubmatic-sample-app included in the SDK directory.

                  

 

Once you've downloaded and installed the PubMatic Android SDK, use the following sections to implement and configure banner ads:

 

 

Display Banner Ad

Use the following steps to include banner ads into your app.

 

Step 1: Define a banner ad slot in your layout XML

The PubMatic SDK provides the custom view class PMBannerAdView used to display banner ad creative. Please included following XML block to your app's Activity or Fragment layout.

 

<com.pubmatic.sdk.banner.PMBannerAdView
        android:id="@+id/banner"
        android:layout_width="320dp"
        android:layout_height="50dp" />

 

Now you can easily use a reference of PMBannerAdView in your Activity or Fragment like this:

 

PMBannerAdView banner = (PMBannerAdView)findViewById(R.id.banner);

 

Optionally, can also create a PMBannerAdView instance in the Activity or Fragment context like this:

 

// Pass activity context in PMBannerAdView
PMBannerAdView banner = new PMBannerAdView(<Context>);
RelativeLayout layout = (RelativeLayout) findViewById(R.id.parent);
LayoutParams params = new LayoutParams(LayoutParams.MATCH_PARENT,
        100);
params.setLayoutDirection(RelativeLayout.ALIGN_PARENT_TOP);
layout.addView(banner, params);

 

Step 2: Create Ad Request

Create a PMBannerAdRequest object and set the targeting parameters:

 

PMBannerAdRequest adRequest = PMBannerAdRequest.createPMBannerAdRequest(
                <PubId>, <SiteId>, <AdId>);

// It is mandatory to set ad size when requesting a banner ad
adRequest.setAdSize(PMAdSize.PMBANNER_SIZE_320x50);

 

For more targeting parameters, see Passing Targeting Information.

 

Step 3: Request Ad

Send the adRequest using loadRequest() from the banner instance:

 

banner.loadRequest(adRequest);

 

Step 4: Deallocate PMBannerAdView

Deallocate the PMBannerAdView instance before your Activity/Fragment is destroyed.

 

banner.destroy();

 

Callback Events Using a Listener

Optionally, you can register a listener to report success and failure callbacks from the ad request:

 

banner.setRequestListener(new PMBannerAdView.BannerAdViewDelegate.RequestListener() {
    @Override
    public void onFailedToReceiveAd(PMBannerAdView adView, final PMError error) {
        // Ad failed callback 
    }

    @Override
    public void onReceivedAd(PMBannerAdView adView) {
        // Ad received successfully
    }
});

 

See PubMatic SDK Error Codes for a detailed description of the PMError object used in the onFailedToReceiveAd() callback.

 

Set Optional Listeners

PubMatic SDK also provides optional listeners that you can register for other callbacks as shown below:

 

Implement respective listeners in place of any place holders.

 

// Invoked when the ad will navigate to a clicked link (or rich media open). 
banner.setActivityListener(<BannerAdViewDelegate.ActivityListener>);
// Set an interface to notify the events of MRAID ads
banner.setRichMediaListener(<BannerAdViewDelegate.RichMediaListener>);
// Set an interface allowing you to control which device features are exposed to rich media ads
banner.setFeatureSupportHandler(<BannerAdViewDelegate.FeatureSupportHandler>);
// Set an interface to notify the activity of internal browser.
banner.setInternalBrowserListener(<BannerAdViewDelegate.InternalBrowserListener>);

 

To fully support all MRAID events please follow the steps in Rich Media (MRAID 2.0) Ads.

 

Enable Auto Refresh Functionality

PubMatic Android SDK provides the optional feature to auto refresh a banner ad after a specified interval. You can set the refresh interval in code using PMBannerAdView.setUpdateInterval(<value in secs>) before calling the loadRequest()method. Use an interval value within a range of 12 to 120 seconds.

 

// Set update interval of say 15 seconds
banner.setUpdateInterval(15);
// Make the ad request to Server
banner.loadRequest(adRequest);

 

Ad Refresh Behavior for Value of Update Intervals

 

Integer value ( i ) in secondsBanner Auto-refresh behavior
i <= 0Ad will not refresh
i > 0 & i <= 12Ad will refresh after every 12 seconds.
i > 12 & i <= 120Ad will refresh after every i seconds
i > 120Ad will refresh after every 120 seconds

 

Multisize Ad Support (Optional)

You can specify multiple sizes in an ad request. Then SSP/Exchange serves the ad with the creative that best fits into those sizes and returns greater CPMs. This flexibility makes a greater number of campaigns/creatives eligible for the current impression, which can lead to increased fill rate.

 

PMAdSize size1 = new PMAdSize(300,50);
PMAdSize size2 = new PMAdSize(640,100);

PMAdSize arr[]= {size1, size2};
adRequest.setOptionalAdSizes(arr);

 

Get the size of the creative if you need to write your own logic to resize the ad slot. For example:

 

@Override
public void onReceivedAd(PMBannerAdView adView) {
    int width = adView.getAdWidth();
    int height= adView.getAdHeight();
    // Use width and height to get Banner Ad view dimensions.
    // Write your custom logic for the new dimensions and
    // set the new dimensions using the adView.setLayoutParams(<LayoutParams>);
}

 

Attachments

    Outcomes