Integrating Inneractive advertising in a LWUIT application
This article explains how to integrate NAX in a Java app based on the LWUIT framework.
Nokia Ad Exchange (NAX) offers an effective and easy-to-use advertising solution that helps developers to monetize their apps. This article illustrates how the NAX Java SDK can be integrated in a Java app that uses LWUIT, the UI framework available on Asha devices to build rich user interfaces.
Setup the Java app on NAX
Before integrating NAX in a Java app, it is necessary to create an app on the NAX dashboard. This allows to generate the unique app ID that will be used to retrieve ads for the app.
Integrating the NAX SDK
To use the NAX functionality, the NAX Java SDK must be downloaded from the NAX dashboard. Once downloaded, it is necessary to add the NAX JAR file to the build path of the Java project. Picture below shows how the NAX library JAR file can be added to a Java project within the Nokia IDE for Java ME.
Integrating NAX with LWUIT
To start, an empty LWUIT Form is created.
public class NaxForm extends Form
A Form object represents a logical screen of a LWUIT app, and is logically divided into three main areas: the Title Bar, the Menu Bar and the Content Pane.
The Content Pane Container is responsible for managing and laying out the main UI elements of the Form.
Setup UI Components
A banner AD unit is typically placed at the top or bottom of the screen. In LWUIT, this can be achieved by using a BorderLayout layout for the Content Pane, that allows to arrange components to fit in five regions: north, south, east, west, and center.
The north (or south) region is used to hold the component responsible for displaying the AD unit. In order to have a clickable banner AD unit, a Button component is used.
The center region is instead used to hold a Container that will contain the main screen UI and its components.
public class NaxForm extends Form
mainContainer = new Container();
adButton = new Button();
Note: The BorderLayout automatically adapts to the sizes of components placed on the various regions: being the adButton initially empty (since no banner is initially available), the mainContainer occupies the whole Content Pane area. This result is important from an user experience point of view, since it avoids having an empty unused spot on the screen, while waiting for an ad to be loaded.
Since LWUIT typically add borders and padding to Button components, we remove these from the Button's Style. This process must be done for both the unselected and the pressed Button states.
adButton.getPressedStyle().setPadding(0, 0, 0, 0);
adButton.getUnselectedStyle().setPadding(0, 0, 0, 0);
Loading the AD unit
NAX ADs are loaded through the IADView.getBannerAdData static method, that accepts two parameters:
- the running MIDlet instance
- the NAX App ID, created as explained in the previous sections
Optionally, a third parameter can contain an Hashtable with parameters that help to target ads in a more precise way
This method returns a Vector containing the data needed to display and manage the AD unit:
- a LCDUI Image that contains the AD image
- a String containing the AD click URL
private void loadBanner()
Vector ads = IADView.getBannerAdData(LwuitNaxMIDlet.instance, "Jappit_LWUITBasedApp_Nokia");
if(ads.size() >= 2)
Image lcduiImage = (Image)ads.elementAt(0);
adLink = (String)ads.elementAt(1);
Since the IADView.getBannerAdData call involves network connectivity, it is necessary to perform that in a separate Thread, like the following sample code snippet shows:
Displaying the AD unit
Once retrieved, the ad image is represented by a standard LCDUI Image, while LWUIT uses its own Image implementation. For this reason, displaying the retrieved AD image in the Button defined above, it is necessary to convert the LCDUI Image to its LWUIT equivalent. This can be done by using the LWUIT's Image.createImage method, that takes the LCDUI Image as argument, and returns the converted LWUIT instance.
Once converted, the LWUIT Image can be displayed within the Button via its setIcon method.
com.sun.lwuit.adImage = Image.createImage(lcduiImage);
Once the AD image is set through the setIcon() method, the Button size changes to adapt to the new content, and the BorderLayout automatically adapts to make the Button visible, so reducing the space occupied by mainContainer, as shown by the following picture.
Refreshing the AD unit
The NAX Java SDK has no build-in feature that allow to auto-refresh the banner once it is loaded. Such a feature, if needed, should then be implemented with custom code.
The following code snippet shows how a Timer object can be used to schedule an auto-refresh after e predefined refreshInterval time:
Handling AD clicks
The last step in the NAX integration is the handling if the user touches the AD unit. When this happens, the corresponding AD unit URL must be opened in the device browser.
This mechanism can be implemented by defining ad ActionListener for the adButton, and calling the MIDlet.platformRequest method when the button gets pressed, as shown by the following code snippet.
This article shows how NAX can be integrated in a Java app that uses the LWUIT UI framework. This approach can be used to easily modify existing Java apps, thanks to its reusable approach, consisting in having app Form instances extending the NaxForm defined above instead of the base Form class.
The attached ZIP file shows a complete example with the full source code of the NaxForm, together with a sample usage: Media:LWUIT NAX.ZIP