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

Banner integration

Last updated on November 15, 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, which 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. This attribute is 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 the 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;

    In your Activity’s onCreate() or your Fragment’s onCreateView() method, set your AdView's domain and 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);.

It is recommended to have one of the below for the right behavior. Note that this applies only when using the OpenX SDK without any adapter:

Option 1


adView.setAutoDisplayOnLoad(true); 
//Above is optional, as by default it is true in the SDK.
adView.setAutoRefreshDelay(your_refresh_value_in_secs);

Option 2


adView.setAutoDisplayOnLoad(false); 
//Remember to show and hide the ad with adView programmatically using 
//adView.show() and adView.hide() respectively.

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