×
Namespaces

Variants
Actions

Integrating Inneractive advertising in a LWUIT application

From Nokia Developer Wiki
Jump to: navigation, search

Needs-update.pngThis article needs to be updated: If you found this article useful, please fix the problems below then delete the {{ArticleNeedsUpdate}} template from the article to remove this warning.

Reasons: hamishwillee (talk) (22 Nov 2013)
Inneractive now work with Nokia developers directly. This article needs to be retested. All references to NAX should be removed as part of testing/update.

This article explains how to integrate NAX in a Java app based on the LWUIT framework.

Article Metadata
Code Example
Source file: Media:LWUIT NAX.ZIP
Tested with
Devices(s): Nokia Asha SDK 1.0 (beta) Emulator
CompatibilityArticle
Created: jappit (27 Jun 2013)
Last edited: hamishwillee (22 Nov 2013)

Contents

Introduction

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.

NAX integration with a LWUIT based Java app

Preliminary steps

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.

Creating of an app on the NAX dashboard

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.

Adding the NAX JAR library file to a Java project in 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
{
Container mainContainer;
Button adButton;
 
public NaxForm()
{
super("NAX Form");
 
super.setLayout(new BorderLayout());
super.setScrollable(false);
 
mainContainer = new Container();
adButton = new Button();
 
addComponent(BorderLayout.CENTER, mainContainer);
addComponent(BorderLayout.SOUTH, adButton);
 
}
}

Note.pngNote: 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.getUnselectedStyle().setBorder(null);
adButton.getPressedStyle().setBorder(null);
 
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:

new Thread(new Runnable()
{
public void run()
{
loadBanner();
}
}

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);
 
adButton.setIcon(adImage);

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.

Automatic layout management handled by the BorderLayout.

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:

new Timer().schedule(new TimerTask() {
 
public void run()
{
asyncLoadBanner();
}
}, refreshInterval);

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.

adButton.addActionListener(new ActionListener() {
 
public void actionPerformed(ActionEvent actionEvent)
{
if(adLink != null)
{
try
{
LwuitNaxMIDlet.instance.platformRequest(adLink);
}
catch(Exception e)
{
}
}
}
});

Summary

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

This page was last modified on 22 November 2013, at 03:28.
157 page views in the last 30 days.