Creating a BlackBerry application that displays an ad

By using the Advertising Service API you can integrate ads into your applications without writing a large amount of Java code.

Best practice: Displaying ads in an application

The way that you display ads in your application can have an effect on the performance of the ads.

Consider the following guidelines:

  • Place ads on the screens that have the highest amount of traffic for your application (for example, place an ad on a screen that appears when an application opens rather than on a screen that requires multiple clicks to navigate to).
  • Place ads in prominent locations on your screens. Placing an ad at the top of the screen can make the ad more visible to BlackBerry device users.
  • Avoid crowding ads with the rest of the content in your application. Ads should be clearly visible so that they are easier to interact with.
  • Customize the display area for ads to fit the design of your application UI.
Back To Top

Using the Banner class to display an ad

The Banner class, which is included in the Advertising Service API, permits you to display ads in your applications. When you create an instance of the Banner class and place the object on a screen, you essentially create a placeholder which sends periodic ad requests and displays the ads that are returned.

When you create a Banner object, you must pass in the zoneId parameter that Research In Motion assigns to you for your application. Your application sends the zoneId parameter to the Advertising Service mediation layer with each ad request. After the mediation layer receives an ad request, the server evaluates the request based on the statistics that are associated with the zone ID, sends the request to the appropriate ad network, and returns an ad to your application. One zoneId can be used with multiple Banner objects in your application.

You can also pass in a test zoneId parameter to test ad functionality. When you specify a test zone ID, the mediation layer returns sample ads that you can use to test the appearance of ads. You can use a test zone ID of 16741 to test ads in your applications.

In the constructor for a Banner object, you can also define the frequency at which the application makes ad requests, and a placeholder image for the display area.

To display the ad, the Advertising Service API creates a browser field (browser.field for BlackBerry devices running BlackBerry Device Software 4.7.1 and earlier and browser.field2 for devices running BlackBerry Device Software 5.0 and later) to render the contents of the ad and inserts the browser field in the Banner object.

For more information about using the Banner class, visit http://www.blackberry.com/developers/docs/7.1.0api/ to see the Advertising Service API Reference.

Additional considerations

  • The Advertising Service API can support up to two active Banner objects on a screen at one time (only one for BlackBerry 6).
  • If your application displays more than one ad (even if on different screens), you should create a separate Banner object for each ad placement. Reusing a Banner object in multiple locations, might cause ads to display incorrectly.
  • You shouldn't attempt to remove a Banner object from a screen without removing the containing field manager as well, as this can lead to issues with other Banner objects.
  • Using a FlowFieldManager object to display Banner objects might cause ads to display incorrectly.
Back To Top

Setting the size of the display area for an ad

When you create a Banner object, you can specify the size of the ads that you want your application to display. After your application sends an ad request, the Advertising Service mediation layer returns an ad that fits the size that you specified. The Advertising Service supports the following sizes of ads, in pixels:
  • 320 x 53: Banner.MMA_SIZE_EXTRA_EXTRA_LARGE
  • 300 x 50: Banner.MMA_SIZE_EXTRA_LARGE
  • 216 x 36: Banner.MMA_SIZE_LARGE
  • 168 x 28: Banner.MMA_SIZE_MEDIUM
  • 120 x 20: Banner.MMA_SIZE_SMALL

You can set the size of the display area by invoking setMMASize() and specifying one of the constants in the Banner class. For example, you can invoke setMMASize(Banner.MMA_SIZE_LARGE) to direct the mediation layer to return ads that are 216 x 36 pixels in size. You can also invoke setMMASize(Banner.MMA_SIZE_AUTO) to permit the Banner object to resize itself automatically to match the size of the ad that the mediation layer returns. This is the default behavior if you do not set the size of the display area in the application code.

As a best practice, you should set the size of the display area in your application. This approach allows you to control the size of the ads that you receive, and arrange the Banner object appropriately on the screen. If you permit the Banner object to resize itself automatically, you should ensure that the layout of your screen can support each of the different sizes.

Back To Top

Display an ad on a screen

  1. Import the required classes and interfaces.
    import net.rimlib.blackberry.api.advertising.app.Banner;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.UiApplication;
  2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The AdDemoScreen class, which is described in step 3, represents the screen that displays the ad.
    public class AdDemo extends UiApplication{
       public static void main(String[] args)
       {
          AdDemo theApp = new AdDemo();
          theApp.enterEventDispatcher();
       }
       public AdDemo()
       {
          pushScreen(new AdDemoScreen());
       }
    }
  3. Create the custom screen by extending the MainScreen class.
    class AdDemoScreen extends MainScreen{
       public AdDemoScreen()
       {
       }
    }
  4. In the screen constructor, create an instance of the Banner class and pass in the zone ID for your application as a parameter. Alternatively, to test ads in your application, pass in the test zone ID of 16741. Invoke setMMASize() and specify a size for the Banner object. Add the Banner object to the screen.
    Banner bannerAd = new Banner(zoneId, null);
    bannerAd.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);            
    add(bannerAd);

    You can see the results of running the above code sample in the following graphic:

Back To Top

Code sample: Displaying an ad on a screen

import net.rimlib.blackberry.api.advertising.app.Banner;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.UiApplication;

public class AdDemo extends UiApplication
{
   public static void main(String[] args)
   {
      AdDemo theApp = new AdDemo();
      theApp.enterEventDispatcher();
   }
   public AdDemo()
   {
      pushScreen(new AdDemoScreen());
   }
}

class AdDemoScreen extends MainScreen
{
   public AdDemoScreen()
   {
      Banner bannerAd = new Banner(zoneId, null);            
      bannerAd.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);            
      add(bannerAd);
   }
}
Back To Top

Enabling test mode

The Advertising Service provides a test mode that you can use to test the appearance of ads in your application. When you enable test mode for a Banner object, the object displays test ads instead of actual ads that are returned from ad networks. These test ads do not generate revenue or any Advertising Service statistics.

You can enable test mode in your application by invoking setTestModeFlag(true) for a Banner object. It's important that you remove this line of code before you publish and release your application, or your application will continue to use test ads instead of actual ads from ad networks.

Back To Top

Customizing the appearance and behavior of the display area for an ad

You can customize the appearance and behavior of the display area for an ad to fit with the design of your application UI.

Item

Description

Transition effect

By default, when an application loads a new ad or transitions between ads, the application displays a black transition effect that makes the ads appear to fade in or fade out. You can turn off the transition effect by invoking enableBannerTransition(false). You can change the color of the transition effect by invoking setBannerTransitionColor() and specifying a color that is supported by the Color class in the BlackBerry Java SDK. For example, to change the transition color to blue, you can invoke setBannerTransitionColor(Color.BLUE).

Focus behavior

By default, when a BlackBerry device user selects an ad, the application displays a blue border around the ad. You can change the color of the border by invoking setBorderColor() and specifying a color that is supported by the Color class in the BlackBerry Java SDK. For example, to change the border color to red, you can invoke setBorderColor(Color.RED).

You can override the default focus behavior for a Banner object by setting the focus behavior in the containing layout manager, forcing the Banner object to inherit the new behavior. You can prevent the Advertising Service API from handling focus behavior by invoking setFocusOverrideFlag(true).

Placeholder image

By default, when an application is waiting to receive an ad from an ad network, the application displays a transparent placeholder image with a border. If you want to create your own placeholder image, you can create a Bitmap object and pass it as a parameter when you create a Banner object.

If you create your own placeholder image, verify that it has the same dimensions as the ads that your application receives.

Back To Top

Customize the display area for an ad

This task demonstrates how you can change the placeholder image, the colors of the focus border, and the transition effect for the display area for an ad.

Before you begin: Create a custom placeholder image that has the same dimensions as the ads that your application receives and store the image with the resources for your BlackBerry application project.
  1. Import the required classes and interfaces.
    import net.rimlib.blackberry.api.advertising.app.Banner;
    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.ui.Color;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.UiApplication;
  2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The AdDemoScreen class, which is described in step 3, represents the screen that displays the ad.
    public class AdDemo extends UiApplication{
       public static void main(String[] args)
       {
          AdDemo theApp = new AdDemo();
          theApp.enterEventDispatcher();
       }
       public AdDemo()
       {
          pushScreen(new AdDemoScreen());
       }
    }
  3. Create the custom screen by extending the MainScreen class.
    class AdDemoScreen extends MainScreen{
       public AdDemoScreen()
       {
       }
    }
  4. In the screen constructor, create an instance of the Bitmap class by invoking getBitmapResource() and passing in the name of the custom placeholder image as a parameter.
    Bitmap customPlaceholder = Bitmap.getBitmapResource("placeholder.png");
  5. Create an instance of the Banner class and pass in the zone ID for your application, the intervals at which the application makes ad requests, and the Bitmap object that you created as parameters.
    Banner bannerAd = new Banner(zoneId, null, 100000, customPlaceholder);
  6. Invoke setBorderColor() and setBannerTransitionColor() to change the color of the border and the transition effect.
    bannerAd.setBorderColor(Color.RED);
    bannerAd.setBannerTransitionColor(Color.RED);
  7. Invoke setMMASize() and specify a size for the Banner object. Add the Banner object to the screen.
    bannerAd.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);
    add(bannerAd);

    You can see the results of running the above code sample in the following graphics.

    The custom placeholder:

    The custom placeholder fading out with a green transition effect:

    The ad fading in with a green transition effect:

    The ad with a green focus border:

Back To Top

Code sample: Customizing the display area for an ad

import net.rimlib.blackberry.api.advertising.app.Banner;
import net.rim.device.api.system.Bitmap;
import net.rim.device.api.ui.Color;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.UiApplication;

public class AdDemo extends UiApplication
{
   public static void main(String[] args)
   {
      AdDemo theApp = new AdDemo();
      theApp.enterEventDispatcher();
   }
   public AdDemo()
   {
      pushScreen(new AdDemoScreen());
   }
}

class AdDemoScreen extends MainScreen
{
   public AdDemoScreen()
   {
      Bitmap customPlaceholder = Bitmap.getBitmapResource("placeholder.png");
      
      Banner bannerAd = new Banner(zoneId, null, 100000, customPlaceholder);
      
      bannerAd.setBorderColor(Color.RED);
      bannerAd.setBannerTransitionColor(Color.RED);
      bannerAd.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);
      add(bannerAd);
   }
}
Back To Top

Positioning the display area for an ad

The way you position a Banner object on a screen can affect the performance of the ads that your application displays. The more prominent the ads are on the screen, the easier it can be for BlackBerry device users to view and interact with the ads. You can use the layout managers in the BlackBerry Java SDK to arrange ads with the rest of your application content.

You should avoid using FlowFieldManager objects to manage screens that contain ads because the FlowFieldManager class is not designed to display browser fields.

A common strategy for positioning ads is to place the ad at the top or bottom of the screen. If your screen extends MainScreen, you can place a Banner object in the title section of the screen so that the ad always appears at the top, or in the status section so that the ad always appears at the bottom. By placing your Banner object in a HorizontalFieldManager before you add it to the screen, you can change the position and appearance of the Banner object by applying the appropriate styles.

Code sample: Positioning an ad at the top center position of the screen

The following code sample demonstrates how to use field managers to display an ad at the top center position of the screen.

class AdDemoScreen extends MainScreen{
    public AdDemoScreen()
    {
        Banner bannerAd = new Banner(zoneID, null);
        bannerAd.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);
        
        VerticalFieldManager vfm = new VerticalFieldManager
            (VerticalFieldManager.NO_VERTICAL_SCROLL 
            | VerticalFieldManager.NO_VERTICAL_SCROLLBAR 
            | VerticalFieldManager.USE_ALL_WIDTH);
        HorizontalFieldManager hfm = new HorizontalFieldManager
            (HorizontalFieldManager.FIELD_HCENTER 
            | HorizontalFieldManager.FIELD_VCENTER);

        hfm.add(bannerAd);
        vfm.add(hfm);
        add(vfm);
    }
}

You can see the results of running the above code sample in the following graphic:

This graphic displays a screen that contains an ad positioned at the top center location of the screen.

For more information about layout managers, see the BlackBerry Java SDK UI and Navigation Development Guide at www.blackberry.com/go/devguides.

Back To Top

Was this information helpful? Send us your comments.