Banner integration

Last updated on May 11, 2018

Overview

Prerequisites

Sample code

Using the Listener interface

Load banner ads in your app

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.

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. Implement all necessary AdEventListener overrides:


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();
		}

		// ... implement AdEventsListener overrides ...
	}
		

and pass your Activity to the AdView as it's being created:

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.

Load banner ads in your app

  1. Define a slot for your banner ad. You can do this by including an XML block in your layout XML or programmatically.

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

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

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

    Allowed XML attributes are:

    Example:

    
    <com.openx.view.plugplay.views.AdView
    	android:id="@+id/adView" 
    	android:layout_width="320dp"
    	android:layout_height="50dp"
    	adType="BANNER"
    	adUnitID="537454411"
    	domain="PUBLISHER-d.openx.net"
    	autoDisplayOnLoad="true"
    	autoRefreshDelay="30"
    	autoRefreshMax="50"
    	flexAdSize = "320x50"
    />
    	

    Option 2: Programmatically create a banner.

    Use the following to create an instance of AdView and add it to your container in the layout:

    
    public AdView(Context context, String domain, String adUnitId, AdUnitIdentifierType adType)

    For example:

    
    AdView adView = new AdView(this, "PUBLISHER-d.openx.net", "537454411", AdConfiguration.AdUnitIdentifierType.BANNER);
    // Example to add the AdView to your container:
    LinearLayout adContainer = (LinearLayout) findViewById(R.id.adContainer);
    if(adView != null)
    {
    	adContainer.addView(adView);
    }
    // Where LinearLayout could be any of your layouts, like ConstraintLayout, GridLayout, RelativeLayout, and so on.
    	
  2. Load an ad.
    						
    private AdView adView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
    	super.onCreate(savedInstanceState);
    	
    	// TODO: Initialize or set your adView variable here.
    	
    	createAd(adView);
    }
    						
    private void createAd(AdView adView) {
     
    	if (adView != null) {
     
    		// Set user parameters to enrich ad request data.
    		UserParameters userParameters = new UserParameters();
    
    		userParameters.setCustomParameter("name", "OpenXDemoApp");
    
     		// Set userparameters on adView:
    		adView.setUserParameters(userParameters);
     
    		// Set predefined flex ad size here.
    		adView.setFlexAdSize(AdConfiguration.OXMAdSize.BANNER_320x50);
     
    		// Or, set your custom flex ad size 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 ad 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. Remember to clean up the AdView inside onDestroy().
    
    @Override
    protected void onDestroy() {
    						
    	super.onDestroy();
    						
    	if (adView != null) {
    						
    		adView.destroy();
    		adView = null;
    						
    	}
    }
    		

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="PUBLISHER-d.openx.net"
	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.