×
Namespaces

Variants
Actions

Getting started with Inneractive Advertisement for Java ME

From Nokia Developer Wiki
Jump to: navigation, search
Featured Article
18 Aug
2013

This article explains how to get started with Inneractive Advertisement for Java ME and describes the steps you need to follow in order to monetize your application by adding banner or interstitial (full screen) ads.

Contents

Inneractive Mobile Advertisement for Java ME

Inneractive Mobile Advertisement is a private mobile advertising exchange offering access to the top ad networks in the world. With one API and one partner, you'll get access to over 120 ad agencies and networks worldwide. The service enables

  • full cross-platform support (including Nokia Asha Software Platform and Series 40)
  • optimization across 120+ ad networks
  • payment in over 200 countries
  • smart, contextual ad selection
  • easy integration to your Java MIDlet with just a few lines of code
  • management of your own ad campaigns, that can be either displayed in your own app, or in applications published by other developers.

The library lets you incorporate in-app advertising and be ready for payments in few minutes. You will also get a single dashboard to track your apps’ performance.

Getting Started

Before you can start using Inneractive’s Mobile Advertisement you will need to sign up for the service in order to be able to generate an application specific App ID. Then you need to add the Innerative plugin to your working project and import the relevant packages.

Signing up

For registration, you will need to provide the following details:

  • Full name
  • Email
  • Company name
  • Website (or app download link)
  • Home country
  • Phone number
  • Expected number of monthly impressions
  • The target platform

You can sign up here.

InneractiveRegistrationForm.png

When targeting MIDlets on Series 40 or Nokia Asha software platform, you need to choose Nokia as your Main working platform. After completing your registration, you will receive an email informing you that your application is being reviewed. As soon as your registration request has been approved, you will receive a welcoming email with your credentials

Generating an App ID

The App ID is used as an identifier that allows you to track revenue generated by a specific application. The App ID is platform specific, so you need different App IDs for the same application that has been ported to other mobile platforms. For a list of supported platforms by the service, see here. The online console includes a dashboard that displays your total revenue broken down by platform.

In order to get an App ID, follow these steps:

  • Log in to the Inneractive Advertisement console, using the credentials you received in the welcoming email.
  • Select the Add App tab.
    AppIdGenerator.png
  • Select the target Platform. For Series 40 and Nokia Asha software platform, choose Nokia.
  • Enter a unique name for your app. The name is allowed to have spaces. However the generated App ID does not contain spaces.
  • If your application is already published, enter the download URL from the relevant Store.
  • Select the category that best describes your app, so that Inneractive can select the most relevant ads.
  • In the Description field, provide as many details as possible about your app and its context, to attract premium advertisers.
  • Set the age group you believe will best define your app audience.
  • If the application retrieves the users’ location, select Yes in the Use location field, in order to enable location-based ads and increase relevancy.

Click Create. The App ID is now created. You can copy it from the console and paste it directly into your code. The App ID follows typically this naming convention: CompanyName_AppName_Platform.

Importing the Inneractive Advertisement Library

Unlike native Java ME APIs, the Inneractive Advertisement library is an external library, and it is distributed as a single .jar file. You will need to retrieve the .jar file and import it to your working project before you can start coding. You can download the library by selecting the SDKs tab from the online console and by choosing the J2ME download link.

InneractiveSDKview.png

For instructions on how to import the library to your working project see Importing external libraries to workspace.

Displaying ads in your MIDlet

There are two types of ads you can display in your app, Banner ads and Interstitial ads. Banner ads can be placed within an ImageItem, CustomItem or a Canvas instance. The size of the Banner is determined automatically by the implementation and depends on the screen resolution of the device from where it is retrieved and the device orientation. Banner ads occupy the entire width of the screen. Interstitial ads are displayed in a new screen (Displayable), occupy the entire content area of the screen and come with two actions:

  • Go, which launches the browser and loads the ad’s target URL
  • Skip, which returns back to the screen (displayable) from where the interstitial ad was launched.

The major difference between these two types of ads, is that the developer needs to handle himself both the placement and the launch of the browser in the case of the Banner ads. Displaying and handling any actions associated with Interstitial ads, are hidden from the developer. The name of the Go and Skip buttons for the Interstitial screen, however can be customized.

Banner Ads can be initialized with or without optional parameters. These are the two available constructors:

  1. Banner Ad initialization without optional parameters
     public static Vector getBannerAdData(MIDlet appMidlet, String appID)
  2. Banner Ad initialization with optional parameters that improve user experience and targeting:
     public static Vector getBannerAdData(MIDlet appMidlet, String appID, Hashtable optionalParams)

The optional parameter argument is a HashTable instance with the following pair of keys and allowed values:

Key Description
IaOptionalParams.Key_Age User's age
IaOptionalParams.Key_Gender User's gender (allowed values: M, m, F, f, Male, Female).
IaOptionalParams.Key_Keywords Keywords relevant to this user's specific session. For example: cars,music,sports (comma separated, w/o spaces).
IaOptionalParams.Key_Unique_Id_Sha1 The IMEI of the device encrypted with sha1
IaOptionalParams.Key_Unique_Id_Md5 The IMEI of the device encrypted with MD5
IaOptionalParams.Key_Location Location string – comma separated list of country, state/province, city. For example: US,NY,NY
IaOptionalParams.Key_Gps_Location GPS location – ISO code location data. In latitude, longitude format. For example: 53.542132,-2.239856 (without spaces)

Both constructors return a Vector with two elements, an Image instance and a URL. It is the developer who needs to place the Banner ad in the MIDlet, launch the browser when the ad is clicked, implement the exception handling and consider security and orientation implications.


The most common option for Banner Ads is to place them within an ImageItem.

BannerAdImageItem.png

The first thing the developer needs to do is instantiate a HashTable object and set the optional parameters that will better target the app’s audience as follows:

HashTable options = new Hashtable();
 
options.put(IaOptionalParams.Key_Age, "30");
options.put(IaOptionalParams.Key_Gender, "M");
options.put(IaOptionalParams.Key_Gps_Location, "40.741014,-73.995781");
options.put(IaOptionalParams.Key_Keywords, "Bargain,Flights,Hotels");
options.put(IaOptionalParams.Key_Location, "US,NY,NY");
options.put(IaOptionalParams.Key_Unique_Id_Sha1, "83a43c4cdb61667feac0cfca516d3270289584b8");
options.put(IaOptionalParams.Key_Unique_Id_Md5, "385e362b7fc97457cb9fb09e029237e7");

The next step is to retrieve the Vector that contains the URL and the Image for the Ad. This operation should be placed within a TimerTask. The getBannerAdData() method is a protected call, that will trigger a security permission request. If the end user does not allow the operation, the Vector will remain null. A NullPointerException will be thrown when an attempt to retrieve its contents is made, in this case. For this reason, the Vector’s elements are retrieved, if the Vector object is not null and only if the Vector has exactly two elements.

The Vector’s first element is type cast to Image and the Vector’s second element to a String. An ImageItem is then initialized that can be appended to the Form using the default layout. In order to make the ImageItem interactive, a Command should be defined which should be set as the ImageItem’s default Command. This is how the TimerTask’s code looks like:

adUpdate = new TimerTask() {
public void run() {
Ad = IADView.getBannerAdData(midlet, "Company_MIDlet_Nokia", options);
 
if(Ad != null && Ad.size() == 2) {
Image image = (Image)(Ad.elementAt(0));
url = (String)(Ad.elementAt(1));
 
if(item != null) {
form.delete(1); // Set to 0 if the Ad is the first item.
}
 
item = new ImageItem("", image, Item.LAYOUT_DEFAULT, "");
form.append(item);
launchBrowser = new Command("OK", Command.OK, 1);
 
item.setDefaultCommand(launchBrowser);
item.setItemCommandListener(midlet);
}
else {
form.append("Cannot display ad \n");
}
}
};
timer.schedule(adUpdate, 0, 600000);

Note, that the third argument in the getBannerAdData() method is optional, though it is highly recommended to set target criteria, in order to deliver ads that better address the app’s audience. The final step is to implement the ItemCommandListener that will catch the ad click and launch the browser using a PlatformRequest:

public void commandAction(Command c, Item item) {
if (c == launchBrowser) {
try {
this.platformRequest(url);
}
catch (ConnectionNotFoundException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}
}

Banner Ads can be placed within CustomItems. This approach requires the creation of a new class that inherits from CustomItem and represents an Ad item. The main MIDlet should pass to the Ad item class its own instance, the Image instance and the URL of the Ad. The Ad item class should have its own implementation of the paint method, where it simply draws the received image, placing the image’s TOP and LEFT corner at the top left coordinate of the CustomItem.

public class AdItem
extends CustomItem {
 
Image image;
String url;
NokiaAdMIDlet midlet;
 
protected AdItem(String label, Image image, String url, NokiaAdMIDlet midlet) {
super(label);
 
this.image = image;
this.midlet = midlet;
this.url = url;
}
 

protected void paint(Graphics g, int w, int h) {
g.drawImage(image, 0, 0, Graphics.TOP | Graphics.LEFT);
}
protected void updateAd(String url, Image image) {
this.url = url;
this.image = image;
repaint();
}
}

The updateAd() method is used when the Ad needs to be replaced with a new one. The current recommendation is to use a maximum timeout value of 10 minutes. In the case of touch enabled devices the Ad item class can notify the main MIDlet when the user taps on the ad, by implementing the pointerPressed() method as follows:

protected void pointerPressed(int x, int y) {
midlet.launchUrl(url);
}

The launchUrl() method, is called from the main MIDlet instance and simply performs a PlatformRequest.

public void launchUrl(String url) {
try {
this.platformRequest(url);
} catch (ConnectionNotFoundException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}

The main MIdlet handles both the creation and the update of the Ad item. If this is the first ad retrieval attempt the Ad item will have a null value. This is the time when it needs to be instantiated. For any subsequent attempts, the Ad item needs to be only updated, and the updateAd() method is called. A timer task is scheduled every 10 minutes. The options variable is a Hashtable that includes pair of keys for targeting a specific audience. The direct_touch trait is set to true here, so that the first tap on the Ad item is caught by the pointerPressed() method. By default, the first tap brings the focus to the Ad item.

protected void startApp() 
throws MIDletStateChangeException {
timer = new Timer();
midlet = this;
options = new Hashtable();
 
options.put(IaOptionalParams.Key_Age, "30");
options.put(IaOptionalParams.Key_Gender, "M");
options.put(IaOptionalParams.Key_Gps_Location, "40.741014,-73.995781");
options.put(IaOptionalParams.Key_Keywords, "Bargain,Flights,Hotels");
options.put(IaOptionalParams.Key_Location, "US,NY,NY");
options.put(IaOptionalParams.Key_Unique_Id_Sha1, "83a43c4cdb61667feac0cfca516d3270289584b8");
options.put(IaOptionalParams.Key_Unique_Id_Md5, "385e362b7fc97457cb9fb09e029237e7");
 
adUpdate = new TimerTask() {
public void run() {
Ad = IADView.getBannerAdData(midlet, "Company_MIDlet_Nokia", options);
 
if(Ad != null && Ad.size() == 2) {
Image image = (Image)(Ad.elementAt(0));
url = (String)(Ad.elementAt(1));
 
if(item == null) {
item = new AdItem("", image, url, midlet);
LCDUIUtil.setObjectTrait(item, "nokia.ui.s40.item.direct_touch", new Boolean(true));
form.append(item);
}
else {
item.updateAd(url, image);
}
}
else {
// Something went wrong
}
}
};
timer.schedule(adUpdate, 0, 600000);
}

Banner Ads can be placed in Canvas instances, for example at the bottom of the screen.

BannerAdCanvas.png

In this case the entire fetch mechanism can be hidden within the Canvas instance. The main MIDlet could remain very simple:

protected void startApp() 
throws MIDletStateChangeException {
 
adCanvas = new AdCanvas(this);
Display.getDisplay(this).setCurrent(adCanvas);
}

The main MIDlet instance needs to be passed as argument to the Canvas object because the getBannerAdData() takes it as the first argument.

We would need to keep track of the Canvas width and height as well as the ad’s width and height in order to calculate the coordinates adX and adY where the ad will be placed within the Canvas. The HashTable contains pair of keys for setting the target audience, while the TimerTask handles the update of the Canvas at regular intervals. The background color is used to clear the Canvas every time a new image needs to be placed in it. This is how the constructor for the Canvas class and its member variables could look like:

public class AdCanvas
extends Canvas
implements InneractiveAdEventsListener {
 
Image image;
 
int adWidth;
int adHeight;
 
int devWidth; // Canvas width
int devHeight; // Canvas height
 
int adX; // the X coordinate for the top left corner of the ad
int adY; // the Y coordinate for the top left corner of the ad
 
String url;
 
Hashtable options;
Timer timer;
TimerTask adUpdate;
 
Vector Ad;
NokiaAdMIDlet midlet;
int backColor; // the background color.
 
protected AdCanvas(NokiaAdMIDlet midlet) {
 
this.midlet = midlet;
devHeight = this.getHeight();
devWidth = this.getWidth();
 
timer = new Timer();
options = new Hashtable();
 
options.put(IaOptionalParams.Key_Age, "30");
options.put(IaOptionalParams.Key_Gender, "M");
options.put(IaOptionalParams.Key_Gps_Location, "40.741014,-73.995781");
options.put(IaOptionalParams.Key_Keywords, "Bargain,Flights,Hotels");
options.put(IaOptionalParams.Key_Location, "US,NY,NY");
options.put(IaOptionalParams.Key_Unique_Id_Sha1, "83a43c4cdb61667feac0cfca516d3270289584b8");
options.put(IaOptionalParams.Key_Unique_Id_Md5, "385e362b7fc97457cb9fb09e029237e7");
backColor = Display.getDisplay(midlet).getColor(Display.COLOR_BACKGROUND);
updateAd();
}
}

The updateAd() method handles the fetching and displaying of the Ad. If we wanted to place the ad centred at the bottom of the screen, we would need to subtract the height of the Ad from the height of the Canvas and set the result value as the Y coordinate of the image’s top left corner. Then we should calculate how much margin there is between the image and the borders of the Canvas, divide the margin by 2 to equally distribute the margin on the left and right side and then use the resulting value as the X coordinate of the image’s top left corner:

private void updateAd() {
adUpdate = new TimerTask() {
 
public void run() {
 
Ad = IADView.getBannerAdData(midlet, "Company_MIDlet_Nokia", options);
 
if(Ad != null && Ad.size() == 2) {
image = (Image)(Ad.elementAt(0));
url = (String)(Ad.elementAt(1));
 
adHeight = image.getHeight();
adWidth = image.getWidth();
adY = devHeight - adHeight;
adX = (devWidth - adWidth) / 2;
repaint();
}
}
};
timer.schedule(adUpdate, 0, 600000);
}

For touch enabled devices, launching the browser, requires checking if the user has tapped on the area defined by the Ad:

protected void pointerPressed(int x, int y) {
if(x >= adX && x <= adX + adWidth && y > devHeight - adHeight) {
try {
midlet.platformRequest(url);
} catch (ConnectionNotFoundException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}
}

The paint method, clears the screen and draws the newly fetched image:

protected void paint(Graphics g) {
if(image != null) {
g.setColor(backColor);
g.fillRect(0, 0, devWidth, devHeight);
g.drawImage(image, adX, adY, Graphics.TOP | Graphics.LEFT);
}
}

Interstitial Ads

Interstitial ads take control of the entire displayable. Interstitial Ads are displayed in the content area of the screen and provide the Skip and Go action. The developer needs to only initialize an interstitial ad by using one of the following constructors:

Interstitial Ad without optional parameter

 public static void displayInterstitialAd(MIDlet appMidlet, String AppID)
  • appMidlet - your application's midlet.
  • appID - An App ID is provided to you upon the creation of an app on your Nokia console.


Interstitial Ad with optional parameter

 public static void displayInterstitialAd(MIDlet appMidlet, String AppID, Hashtable optionalParams)
  • appMidlet - your application's midlet.
  • appID - An App ID is provided to you upon the creation of an app on your Nokia console.
  • optionalParams - you can add optional parameters to improve user experience and targeting.

The optional parameters for interstitial ads are similar to the ones available for Banner Ads with the addition of the customization for the names of the GO and SKIP Commands:


Key Description
IaOptionalParams.Key_Age User's age
IaOptionalParams.Key_Gender User's gender (allowed values: M, m, F, f, Male, Female).
IaOptionalParams.Key_Keywords Keywords relevant to this user's specific session. For example: cars,music,sports (comma separated, w/o spaces).
IaOptionalParams.Key_Unique_Id_Sha1 The IMEI of the device encrypted with sha1
IaOptionalParams.Key_Unique_Id_Md5 The IMEI of the device encrypted with MD5
IaOptionalParams.Key_Location Location string – comma separated list of country, state/province, city. For example: US,NY,NY
IaOptionalParams.Key_Gps_Location GPS location – ISO code location data. In latitude, longitude format. For example: 53.542132,-2.239856 (without spaces)
IaOptionalParams.Key_interstitial_GO_btn The Text that will be displayed on the 'GO' button of the interstitial Ad, in cases that it's possible. The text can be up to 5 letters only, no numbers or symbols.
IaOptionalParams.Key_interstitial_SKIP_btn The Text that will be displayed on the 'SKIP' button of the interstitial Ad, in cases that it's possible. The text can be up to 5 letters only, no numbers or symbols.

Interstitial Ad with Ad listener

For even better interaction and user engagement, the displayInterstitialAd() method can be called with a listener that enables your app to react to events such as the user clicking on the ad:

 public static void displayInterstitialAd(MIDlet appMidlet, String AppID, InneractiveAdEventsListener iaListener)
  • appMidlet - your application's midlet.
  • appID - An App ID is provided to you upon the creation of an app on your Nokia console.
  • iaListener - InneractiveAdEventsListener.


Interstitial Ad with optional parameter and Ad listener

 public static void displayInterstitialAd(MIDlet appMidlet, String AppID, Hashtable optionalParams, InneractiveAdEventsListener iaListener)
  • appMidlet - your application's midlet.
  • appID - An App ID is provided to you upon the creation of an app on your inneractive console.
  • optionalParams - you can add optional parameters to improve user experience and targeting.
  • iaListener – InneractiveAdEventsListener


Security Permissions

The following option should also be included before signing the application:

MIDlet-Permissions-Opt: javax.microedition.io.Connector.http,javax.microedition.io.Connector.https

Article Metadata
This page was last modified on 18 August 2013, at 07:33.
118 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×