You are here: Developers > OpenX Mobile Android SDK > Banner integration

Banner integration

Last updated on August 23, 2017

Overview

Prerequisites

Sample code

Load banner ads in your app

Using the Listener interface

Data enrichment for banners

Refreshing ads

Manual banner

Prerequisites

  1. Before integrating bannerThis is an ad that appears on a web page which is typically hyperlinked to an advertiser’s website. Banners can be images (GIF, JPEG, PNG), JavaScript programs or multimedia objects (For example, Java). ads in your app, you’ll need to create a mobile ad unit or make sure you know which existing ad unitThe smallest inventory component that represents the space on a site where ads display. to use.
  2. Update your Android manifest, as described in Android SDK integration.

Sample code

For a complete example, please see BannerActivity.java in the AndroidSDKDemo workspace provided in the SDK zip file.

Load banner ads in your app

  1. Define a slot for your banner ad in your layout XML.

    The OpenX Mobile Android SDK provides a custom View subclass, AdView, that handles requesting and loading ads.

    Start by including this XML block to your Activity’s or Fragment’s layout.

    Allowed XML attributes are:

    • adType= Denotes the adtype. Use "BANNER" for a banner ad or "INTERSTITIAL" for an interstitialA full-screen ad displayed in content transitions. For example, a video ad that loads between levels of a mobile game. ad. These are case-sensitive.
    • adUnitID= Denotes the adunit. You will create this in the OpenX UI.
    • flexAdSize = Denotes the ad sizes allowed for this ad unit. See Flex ads.
    • autoRefreshDelay = Time in seconds at which ad needs to be refreshed.
    • autoRefreshMax = Number of times the ad can be refreshed once it is displayed. By default, there is no maximum and the ad will continue to refresh until the AdView is destroyed.
    • autoDisplayOnLoad= Set to true if the ad has to be shown immediately. Otherwise set to false.
    • domain= Denotes the domain on which an adUnitID was created.

    Example:

    
    <com.openx.view.plugplay.views.AdView
    	android:id="@+id/bannerad"
    	adType="BANNER"
    	adUnitID="537454411"
    	autoDisplayOnLoad="true"
    	autoRefreshDelay="30"
    	autoRefreshMax="50"
    	domain="ox-d.mobile.servedbyopenx.com"
    	flexAdSize = "320x50"
    	android:layout_width="320dp"
    	android:layout_height="50dp"/>
    	
  2. Load an ad into the banner slot.

    In your Activity or Fragment code, declare an instance variable for your AdView:

    
    private AdView adview;

    You should already have created an ad unit in the OpenX UI and received an ad unit ID. You will use it now to identify that ad unit in your app and request ads from OpenX that are relevant for your users.

    In your Activity’s onCreate() or your Fragment’s onCreateView() method, set your AdView's domain & ad unit ID, then simply call loadAd() to fetch and display the ad.

    Example:

    						
    private void createAd() {
     
    	try {
     
    		adView = new AdView(this, "ox-d.mobile.servedbyopenx.com", "537454411", AdConfiguration.AdUnitIdentifierType.BANNER);
     
    	}
     
    	catch (AdError e) {
     
    		Log.e(TAG, "AdView failed");
     
    		return;
     
    	}
     
    	//placement: Specify the position in the view, where you want the banner to be placed
     
    	RelativeLayout.LayoutParams BannerPosition = new RelativeLayout.LayoutParams(RelativeLayout.LayoutParams.WRAP_CONTENT, RelativeLayout.LayoutParams.WRAP_CONTENT);
     
    	BannerPosition.addRule(RelativeLayout.ALIGN_PARENT_TOP);
     
    	BannerPosition.addRule(RelativeLayout.CENTER_HORIZONTAL);
     
    	if (adView != null) {
     
    		adView.setLayoutParams(BannerPosition);
     
    		//set user parameters to enrich ad request data
    		UserParameters userParameters = new UserParameters();
    		userParameters.setCity("MenloPark");
    		userParameters.setCustomParameter("name", "OpenXDemoApp");
    		adView.setUserParameters(userParameters);
     
    		//set predefined flex adsize here
    		adView.setFlexAdSize(AdConfiguration.OXMAdSize.BANNER_320x50);
     
    		//or set your custom flex adsize as a string
    		//adView.setFlexAdSize("320x50,400x350");
     
    		//Set an interval at which this banner should refresh
    		adView.setAutoRefreshDelay(30);
     
    		//Set the maximum number of times the banner should refresh
    		adView.setAutoRefreshMax(3);
     
    		//Auto display a banner once loaded
    		adView.setAutoDisplayOnLoad(true);
     
    		//Set an add event listener to get notified of the ad life cycle
    		adView.addAdEventListener(this);
     
    		//load an ad
    		adView.load();
     
    		//Tip: call just adView.setAutoDisplayOnLoad(true); without adView.show();
    		//Tip: or call adView.setAutoDisplayOnLoad(false); followed by adView.show();
     
    	}
     
    }
    
    
    
  3. When the hosting Activity or Fragment is destroyed, be sure to also destroy the AdView by calling:

    adview.destroy();

Using the Listener interface

Add an AdEventsListener and implement those callbacks to get notifications for various events. For details, see Callbacks.

To listen for events, you’ll need to implement the listener interface:


public class ExampleActivity extends Activity implements AdEventsListener
	{
		@Override
		public void adDidLoad(AdView adView, AdDetails adDetails) {
		Toast.makeText(getApplicationContext(), 
			"Banner successfully loaded.", Toast.LENGTH_SHORT).show();
		}

	// ... other AdEventsListener methods ...
}

and pass your Activity to the AdView as it's being created (see Step 2, above):

adView.addAdEventListener(this);

AdDetails includes a transactionId. The transactionId is a unique identifier for an ad, which you can use for managing and reporting ad quality issues.

Data enrichment for banners

See Request parameters for details on parameters you can include to enrich data in the ad requestCommunication from a web browser or app to an ad server to display an ad..

Refreshing ads

The Adview will automatically refresh your ad unit at a time interval that you set using the OpenX user interface.

You can also programmatically change the settings for auto-refresh on a particular AdView using setAutoRefreshDelay() and setAutoRefreshMax() methods.

  • setAutoRefreshDelay() - Interval at which an ad has to be refreshed.
  • setAutoRefreshMax()- Number of times an ad can be refreshed, if you want to set a maximum. By default, there is no maximum.

//Time at which displayed ad has to be refreshed.
adView.setAutoRefreshDelay(30);
adView.setAutoRefreshMax(50);
				
OR
<com.openx.view.plugplay.views.AdView
...
autoRefreshDelay="30"
autoRefreshMax="50"
... />

Notes:

  • Server-side refresh values will take precedence over client-side refresh values.
  • The allowed range of the refresh interval is 30 to 125 seconds.
  • If you do not set any refresh interval, the ad will refresh at a default interval of 60 seconds.
  • If you do not want an ad to be refreshed, please set the interval to 0 in adView.setAutoRefreshDelay(0);.

Manual banner

If you would like to control the visibility of a banner ad, you can use AdView's show() and hide() methods. A manual banner generally is an ad that does not have refresh capability. You can disable the refresh on an ad unit by setting autoRefreshDelay to "0". Or, use setAutoRefreshDelay(0).

Example:


<com.openx.view.plugplay.views.AdView
	android:id="@+id/adBanner_layout_manual"
	adType="BANNER"
	adUnitID="537454411"
	autoDisplayOnLoad="false"
	autoRefreshDelay="0"
	domain="ox-d.mobile.servedbyopenx.com"
	flexAdSize = "320x50"
	android:layout_width="320dp"
	android:layout_height="50dp"
	android:layout_alignParentTop="true"
	android:layout_centerHorizontal="true" />

AdEventsListener provides adDidLoad() when the ad is loaded. You can then choose to show the ad using:


adView.show()

When you want to hide the ad, call:


adView.hide()

See AdViewManualBannerActivity.java for an example.

Feedback form