OpenX Android Widget

This widget was written by Funky Android Ltd. and is made available under the following BSD style license;

Copyright (c) 2009, Funky Android (www.funkyandroid.com)
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions
are met:

1) Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer.

2) Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution.

3) Neither the name of the project nor the names of its contributors 
may be used to endorse or promote products derived from this software 
without specific prior written permission.
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Getting Started - OpenX

In order to use the widget you will need to do the following

  1. Open an OpenX Hosted account or download an install the OpenX Server
  2. Follow the video on the OpenX site on getting started with OpenX.
    Please Note: You should create a zone which serves images for the size you need. We use IAB Half Banner (234x60) for the size because it's small enough to display on a QVGA screen. If you're only targeting larger displays you can use a larger banner size. You can have multiple zones for one application if you want to control the ads shown in different parts of your application separately.
  3. Get the server name that hosts your adverts.
    You can do this by selecting Zones from the menu on the left, then selecting the Invocation Code option for the appropriate zone from the list, then select Image Tag from the drop down list and press the little arrow to the right of the drop down list, and then look for the image URL in the code provided. In the code for our zone we had ...<img src='http://d1.openx.org/...., so the server name for us is d1.openx.org.
  4. Get the ID of the zone (or zones) you wish to serve in your application.
    The quickest way of doing this we've found is to select Zones from the menu on the left, click on the name of the zone you want from the list, and then get the number from the URL (which will end zoneId=xxxx where xxxx is the zone ID).
  5. Make sure you have at least one banner associated with the zone in OpenX, and it must be an image banner.
    Without this there will be nothing for the application to serve so it'll be difficult to determine if everything is working. You can upload a dummy image if you want, all that is important is that there is something for OpenX to serve.

You've now done all you need to do on the OpenX side. You can alter the configuration as you wish, but we'd recommend starting simple so that any potential issues are easily found.

Getting Started - The Android App

There are only three things you'll need to do to serve ads in your app. These are;

  1. Include the widget source code in your source code tree.
    The only file you need is src/com/funkyandroid/openx/widget/OpenXWidget.java. You should copy this into your applications development tree in the same location.
  2. Include the widget layout definition.
    You can find an example of a layout with the widget included in the demo app at res/layout/main.xml. The widget definition is;
    <com.funkyandroid.openx.widget.OpenXWidget
			android:id="@+id/advert"
			android:layout_width="fill_parent"
			android:layout_height="60px"
			android:layout_weight="0"
			android:background="#888">
    We've set the height to 60px because we're using a 234x60 pixel banner and setting this lets the OS know how much space the ad needs. We've set a background because we think it looked pretty :).
    The widget is derived from a standard Android ImageView, so any attributes you can set for an ImageView can be set for the widget, but do not set a click listener as this will stop the ad from working.
  3. Set the server name and zone ID in your application.
    In the example application this is done in src/com/funkyandroid/openx/Main.java. The important lines are; 
    OpenXWidget widget = (OpenXWidget)findViewById(R.id.advert);
widget.setServer("d1.openx.org");
widget.setZoneId(90810);
    You'll need to replace the server specified (in our case d1.openx.org) with the server from step 3 of the OpenX instructions above, and you'll need to replace the zoneId (in our case 90810) with the zone ID from step 4 of the OpenX instructions above.

You're then ready to roll.

Troubleshooting

The demo application will serve an ad for AndAppStore, so it's a good place to start. If you change the values in the demo application for your server and zone and you use an IAB Half Banner for your zone you can simply update Main.java with your values and you should see your ads served (if not you should check your OpenX configuration, your zones ID, and your OpenX server name). If you're not using an IAB Half Banner zone then you'll also need to update the main.xml layout file to alter the size of the widget.

Things to remember