Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
 

net.rimlib.blackberry.api.advertising.app
Class Banner

java.lang.Object
  |
  +--HorizontalFieldManager
        |
        +--net.rimlib.blackberry.api.advertising.app.Banner
public final class Banner
extends HorizontalFieldManager

The Banner class manages all the resources that are necessary for embedding dynamic ad content into an application. In order to use a Banner object, in the constructor, you must specify the unique placement ID that Research In Motion assigns you for your application. The placement ID is sent with each ad request so that the network can uniquely identify the ad placement and make an informed decision on the type of ad to return to the application based on statistics associated with the ad placement and configuration specified in the Advertising Service developer portal. To log in to the developer portal, visit adservices.blackberry.com.

Creating and adding ad banners to a screen

To allow your application to receive ads, you only need to create a Banner object and add it to a screen. No other interactions between your application and the Banner object are required. The Banner object sends periodic ad requests automatically, handles all user interaction, and depending on the type of ad, invokes the necessary core applications after the user clicks the ad.

For more details about this service, see the Advertising Service SDK Development Guide at www.blackberry.com/go/adservicedocs.

The following code sample demonstrates how to create a simple screen that displays a Banner object: 
 import net.rim.device.api.ui.container.MainScreen;
 import net.rim.blackberry.api.advertising.app.Banner;

 public class AppScreen extends MainScreen
 {
     public AppScreen()
     {
         Banner banner = new Banner(PLACEMENT_ID, null);
         banner.setMMASize(Banner.MMA_SIZE_EXTRA_LARGE);
         add(banner);
     }
 }

Targeting multiple software versions

Depending on the BlackBerry Device Software version that your application is designed to run on, you might have to invoke setMMASize(int size) to set the size of the display area for the ad. For applications that run on a version earlier than 5.0, you must set the size. For applications that run on 5.0 and later, if you do not set the size, the Banner object resizes itself automatically to match the size of the ad that the server returns.

On versions of BlackBerry Device Software earlier than 6.0, the Advertising Service API can support up to two active Banner objects in the foreground at one time. On BlackBerry 6, the Advertising Service API can support one Banner object in the foreground at one time, and you should avoid adding a Banner object to a screen that already contains a browser field object.

Reusing and removing ad banners

If your application displays more than one ad (even if on different screens), you should create a separate Banner object for each ad placement. If you attempt to reuse a Banner object in multiple locations, ads might not display correctly. If you want to remove a Banner object from a screen, you might need to remove the field manager that contains the Banner object as well. If you remove only the Banner object, this might lead to issues with other Banner objects.

Field Summary
static int MMA_SIZE_AUTO
          Allows the Banner object to resize itself automatically to match the size of the ad that the server returns.
static int MMA_SIZE_EXTRA_EXTRA_LARGE
          Sets the size of the Banner object to 320x50 pixels.
static int MMA_SIZE_EXTRA_LARGE
          Sets the size of the Banner object to 300x50 pixels.
static int MMA_SIZE_LARGE
          Sets the size of the Banner object to 216x36 pixels.
static int MMA_SIZE_MEDIUM
          Sets the size of the Banner object to 168x28 pixels.
static int MMA_SIZE_SMALL
          Sets the size of the Banner object to 120x20 pixels.
 
Constructor Summary
Banner(int zone, java.util.Hashtable metadata)
          Constructs a Banner object used to manage ad content for the given placement ID.
Banner(int zone, java.util.Hashtable metadata, int frequency, Bitmap placeHolderImage)
          Constructs a Banner object used to manage ad content for the given placement ID.
 
Method Summary
 void enableBannerTransition(boolean bannerTransitionFlag)
          Turns on or turns off the ad transition effect.
 boolean getFocusOverrideFlag()
          Retrieves the status of a Banner object’s ability to handle focus behavior.
 int getMMASize()
          Retrieves the size of the display area for an ad.
 boolean getTestModeFlag()
          Retrieve the status of testMode.
 boolean keyChar(char ch, int status, int time)
           
 void setBannerTransitionColor(int bannerTransitionColor)
          Sets the color of the transition effect for the display area for an ad.
 void setBorderColor(int bannerBorder)
          Sets the color of the focus border for the display area for an ad.
 void setFocusOverrideFlag(boolean overrideFocusFlag)
          Turns on or turns off the capability for a Banner object to handle focus behavior.
 void setMetadata(java.util.Hashtable metadata)
          Deprecated. Updates the metadata that is sent with ad requests. After you invoke this method, the ad request URL is automatically rebuilt to reflect the changes to the metadata.
 void setMinimalExtentIntially(boolean minimalFlag)
          Sets the initial size of a Banner object to 0x0 pixels.
 void setMMASize(int size)
           Sets the size of the display area for an ad.
 void setTestModeFlag(boolean testModeFlag)
          set to true to retrieve test ads, set to false otherwise.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MMA_SIZE_AUTO

public static final int MMA_SIZE_AUTO
Allows the Banner object to resize itself automatically to match the size of the ad that the server returns. This field is only necessary in applications running on BlackBerry Device Software versions earlier than 5.0. For applications that run on BlackBerry Device Software 5.0 and later, if you don't invoke setMMASize() at all, the Banner resizes itself automatically by default.

MMA_SIZE_EXTRA_EXTRA_LARGE

public static final int MMA_SIZE_EXTRA_EXTRA_LARGE
Sets the size of the Banner object to 320x50 pixels.

MMA_SIZE_EXTRA_LARGE

public static final int MMA_SIZE_EXTRA_LARGE
Sets the size of the Banner object to 300x50 pixels.

MMA_SIZE_LARGE

public static final int MMA_SIZE_LARGE
Sets the size of the Banner object to 216x36 pixels.

MMA_SIZE_MEDIUM

public static final int MMA_SIZE_MEDIUM
Sets the size of the Banner object to 168x28 pixels.

MMA_SIZE_SMALL

public static final int MMA_SIZE_SMALL
Sets the size of the Banner object to 120x20 pixels.
Constructor Detail

Banner

public Banner(int zone,
              java.util.Hashtable metadata)
Constructs a Banner object used to manage ad content for the given placement ID. In the constructor, the placement ID that are passed to the constructor are automatically appended to the ad request URL that is sent to the server to request an ad.
Parameters:
zone - Zone id of the publisher site
metadata - null setMetadata(Hashtable)

Banner

public Banner(int zone,
              java.util.Hashtable metadata,
              int frequency,
              Bitmap placeHolderImage)
Constructs a Banner object used to manage ad content for the given placement ID. In the constructor, you have the option of passing in the frequency that ad requests are sent for new ads, and a placeholder image that replaces the default placeholder image for the ad as parameters.
Parameters:
zone - Zone id of the publisher site
metadata - null setMetadata(Hashtable)
frequency - The frequency that the Banner object makes requests for new ads (optional). The default value is 60000 ms (60 seconds) and any value less than 60 seconds defaults to 60 seconds as this is the highest frequency that is supported.
placeHolderImage - a Bitmap object that replaces the default placeholder image for the ad (must have the same dimensions as the ads that your application receives)
Method Detail

enableBannerTransition

public void enableBannerTransition(boolean bannerTransitionFlag)
Turns on or turns off the ad transition effect. The ad transition effect makes ads appear to fade in or fade out when a new ad is loading or ads are changing. By default, the transition effect is set to true. To turn off the transition effect, invoke enableBannerTransition(False).
Parameters:
bannerTransitionFlag - false to turn off the transition effect and true otherwise

getFocusOverrideFlag

public boolean getFocusOverrideFlag()
Retrieves the status of a Banner object’s ability to handle focus behavior.
Returns:
true if the focus behavior is overridden and false otherwise

getMMASize

public int getMMASize()
Retrieves the size of the display area for an ad.
Returns:
the size of the ad.

getTestModeFlag

public boolean getTestModeFlag()
Retrieve the status of testMode.
Returns:
true if testmode is preferrred and test ads are retrieved, by default its set to false

keyChar

public boolean keyChar(char ch,
                       int status,
                       int time)

setBannerTransitionColor

public void setBannerTransitionColor(int bannerTransitionColor)
Sets the color of the transition effect for the display area for an ad. The default color for the transition effect is Color.BLACK. You can change the color to any color supported by Color class.
Parameters:
bannerTransitionColor - the color of the border

setBorderColor

public void setBorderColor(int bannerBorder)
Sets the color of the focus border for the display area for an ad. The default color for the focus border is Color.BLUE You can change the color of the focus border to any color supported by the Color class. In the case that setFocusOverrideFlag(boolean overrideFocusFlag) is false or not set, the application invokes setBorderColor to set the focus border to the default color.
Parameters:
bannerBorder - the color of focus border for the ad

setFocusOverrideFlag

public void setFocusOverrideFlag(boolean overrideFocusFlag)
Turns on or turns off the capability for a Banner object to handle focus behavior. By default, the focus override flag is set to false. To turn off the capability for a Banner object to handle focus behavior, invoke setFocusOverrideFlag(True) so that focus behavior is handled by the parent manager.
Parameters:
overrideFocusFlag - true to override the focus behavior and false otherwise

setMetadata

public void setMetadata(java.util.Hashtable metadata)
Deprecated. Updates the metadata that is sent with ad requests. After you invoke this method, the ad request URL is automatically rebuilt to reflect the changes to the metadata.

Parameters:
metadata - a Hashtable object that contains the metadata about the user

setMinimalExtentIntially

public void setMinimalExtentIntially(boolean minimalFlag)
Sets the initial size of a Banner object to 0x0 pixels. In cases where an ad might not display correctly (such as when a user is without network coverage), you can invoke this method to set the initial extent of a Banner object to 0x0 so that a blank placeholder isn't displayed if the ad does not load.
Parameters:
minimalFlag - true to set the initial extent of the Banner object to 0,0 and false otherwise

setMMASize

public void setMMASize(int size)

Sets the size of the display area for an ad. Depending on the BlackBerry Device Software version that your application is designed to run on, invoking this may or may not be necessary. For applications that run on a version earlier than 5.0, you must set the size. For applications that run 5.0 or later, if you do not set the size, the Banner object resizes itself automatically to match the size of the ad that the server returns. 

 Banner.MMA_SIZE_AUTO
 Banner.MMA_SIZE_SMALL
 Banner.MMA_SIZE_MEDIUM
 Banner.MMA_SIZE_LARGE
 Banner.MMA_SIZE_EXTRA_LARGE
 Banner.MMA_SIZE_EXTRA_EXTRA_LARGE
Parameters:
size - the size of the Banner object

setTestModeFlag

public void setTestModeFlag(boolean testModeFlag)
set to true to retrieve test ads, set to false otherwise.
Parameters:
testModeFlag -  

 Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD