Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Integrated

Ideally, your app should integrate and work with other apps on a user's BlackBerry device. Integrating with an app means sharing data and functionality. Whether your app is sending data to another app, or whether it borrows that app's functionality, integrating allows you to create a seamless and responsive user experience that gives your users access to what they need when they need it.


This diagram illustrates application integration between the Contacts application and the Bookshelf application.

What are the benefits of integrating with other apps?

  • Use what's already built. You can use the existing features and functions of core apps and third-party apps to make your app an extension to the BlackBerry experience.
  • Lower the learning curve. Users don't have to stop and learn how to access your app because it's integrated with apps they already know and use. This approach helps to provide an intuitive and seamless experience for the user, which can often decrease user frustration and increase app adoption.
  • Become part of the user's routine. An integrated app can become an integral app. If a core or third-party app is already part of a user's routine, by integrating with that app, you can provide consistent behaviors and essential features that can also become part of the user's routine.

Approaches to integrating your app

You can integrate your app by using any of the following approaches.

Approach

Examples

Invoke an app and pass information to the app.

You can invoke the appropriate functionality on a BlackBerry device, depending on the type of data you recieve. For example, if a phone number appears, you can pass that phone number to the Phone, and make a call.

Integrate with existing or new content handlers.

Your app can automatically send it to the appropriate core app for handling when particular types of content or files are sent to a user. For example, if a Microsoft Word document is sent to a user, it automatically is sent by your app to Documents To Go to be opened and read.

Integrate directly into an app

You can add links to your app inside another app on a BlackBerry device. For example, you could create a custom menu item which allows a user to invite a BlackBerry Messenger contact to join your app. You can also add and embed custom UI fields in core apps.

Integrating by invoking a core app

Invoking an app provides an integrated experience for your users. When you invoke an app, you pass data from your app to a core app, such as the Calendar, Contacts, or Search apps. This allows you to leverage the functionality present on all BlackBerry devices to enhance your user's experience.

For example, in the Bookshelf app, a BlackBerry device user can indicate that a book is loaned by clicking a menu item, such as Loan, which launches the Contacts app and retrieves contact information. From the Contacts app, the user can return to the Bookshelf app and log the information about the person that the book was loaned to.

You can use the Invoke API in the net.rim.blackberry.api.invoke package to invoke core apps and pass data to those apps. Core apps you can invoke include Contacts, Calculator, Calendar, Camera, BlackBerry Maps, MemoPad, Messages, Phone, Search, and Tasks.

To invoke a core app from your app, you can use Invoke.invokeApplication(int appType, ApplicationArguments args), where appType represents the core app that you are invoking, and args represents the data you are passing to the app.

Code sample: Invoking the Phone app

int appType = Invoke.APP_TYPE_PHONE;
ApplicationArguments appArgs = new PhoneArguments(PhoneArguments.ARG_CALL, "519-555-5555");
Invoke.invokeApplication(appType, appArgs);

An effective use of the Invoke API is to pair it with the ApplicationMenuItem class, which is provided in the net.rim.blackberry.api.menuitem package. When you pair the Invoke API with ApplicationMenuItem, you can provide the user with the ability to launch the invoked app and return to your app by using menu items. For more information about menu items, see Adding custom menu items.

Handling content

Another approach to creating a seamless user experience is to make sure your app can handle content by integrating with existing or new content handlers. For example, when a user clicks a URL to an audio book, the media player opens and plays the audio book.

The Content Handler APIs, which are provided in the javax.microedition.content and net.rim.device.api.content packages, allow apps to integrate with and use functionality in third-party and core apps that use these APIs. For example, DataViz, in the Documents To Go apps, use the Content Handler APIs to register their apps as the content handlers for various document types. This suite of apps that is preloaded on most BlackBerry devices also provides handles to allow third-party apps to invoke the Documents To Go apps with the supported document types. For example, your app can invoke Documents To Go by using the Content Handler APIs and the URL to a spreadsheet or text document.

Using the Content Handler APIs, you can register your app to handle specific files based on their MIME type or file extension or you can use these APIs to query for specific content handlers and then invoke the handler.

To make an app that is a content handler, you must register the app with the Registry API by using a unique ID. As part of the registration, you also specify the file types that the app can handle along with the actions that it supports for those files types. For example, you can register an app to print files of a specified type. Once your app is registered as a content handler, other apps can query the registry to get information about the content types and actions this content handler supports, as well as invoke the content handler.

Code sample: Registering an app as a content handler

private static String ID = "com.rim.samples.device.chapidemo";
private static String CLASSNAME = ID + ".CHAPIDemo";

private static void registerApp()
{
    String[] types      = { "text/csv" };
    String[] suffixes   = { ".csv" };
    String[] actions    = { ContentHandler.ACTION_OPEN };
    
    Registry registry = Registry.getRegistry( CLASSNAME );
    registry.register( CLASSNAME, types, suffixes, actions, null, ID, null);
}

To invoke a content handler, your app must initialize an Invocation instance with the information required to identify the content and/or the content handler. Typically, this information could include the URL, type, action, and content handler ID. Your app may also supply arguments and data, and specify whether a response is required. To invoke a core app that is a content handler, you can use the net.rim.device.api.content.BlackBerryContentHandler class, which provides IDs for all core app handlers on the device. These IDs are used with the Invocation class to invoke a specific content handler, or with the Registry class to retrieve a specific ContentHandler class. You start the invocation request by calling the Registry.invoke() method.

Code sample: Invoking the Media application by using a URL

//Create an Invocation instance with the file URL
Invocation invocation = 
         new Invocation("file:///SDCard/BlackBerry/music/001.mp3"); 

//Retrieve a Registry object
Registry _registry = Registry.getRegistry("myPackageName.myClass");

//Invoke the content handler
_registry.invoke(invocation);

Find out more

For more information about handling content, visit the following resources:

Adding custom menu items

To integrate your app with core apps, you can add a custom menu item. By adding custom menu items in core apps, you can provide a seamless experience for your users, where they can launch your app from another app they use frequently. For example, you can add a menu item called Loan Book to the Contacts application. When the user clicks Loan Book, the Bookshelf app opens and displays the screen for logging the loaned book.


This screen shows a custom menu item.

You can define menu items to display in core apps by using the ApplicationMenuItem class, which is defined in the net.rim.blackberry.api.menuitem package.

The ApplicationMenuItem instance you create must be registered with the ApplicationMenuItemRepository class. The ApplicationMenuItemRepository class provides the constants that specify the core app that your menu item appears in. For example, the MENUITEM_MESSAGE_LIST constant specifies that the menu item appears in the list view of the Messages application, or the MENUITEM_SYSTEM constant specifies that your menu item appears in most core apps.

To specify where your menu item appears in the menu list, assign an Integer value to represent the display order of the menu item. Positions are relative, so a lower number corresponds to a higher position in the menu. In the following example, the Loan Book menu item has an order value of 0x350100, which displays the menu item lower in the menu (higher numbers mean the menu item appears lower in the menu and lower values mean the item appears higher in the menu).

When an ApplicationMenuItem is invoked, the core app passes a context object to your app. The context that is returned depends on the core app from which your menu item was invoked. In the following example, the context returned is a contact.

Code sample: Creating a custom menu item in the Contacts app

int placement = 0x350100;
ApplicationMenuItem ami = new ApplicationMenuItem(placement)
{
    public Object run(Object context)
    {
        if (context instanceof Contact)
        {
            myContact = (Contact)context;
            //do something with the contact info
        }
        return null;
    }
    public String toString()
    {
        return "Loan Book";
    }
};

//register the menu item to display when the user views a contact
ApplicationMenuItemRepository amir = ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, ami);

Find out more

For more information about creating custom menu items, see Integrating with apps.

Adding application icons

The Home screen of the BlackBerry device is the most visible and most accessed area. You can provide quick and easy access to your app by adding an icon to the Home screen. When the user clicks the icon, your app is launched. For added visual appeal, you can create a rollover effect for the icon, where the icon changes when the icon receives focus.


This screen displays the home screen and a custom home screen icon.

You can add an application icon and specify rollover effects by changing the properties for the application project in the BlackBerry Java Plug-in for Eclipse. The application properties for the project are contained in the BlackBerry_App_Descriptor.xml file. For more information about changing project properties, see the BlackBerry Java Plug-in for Eclipse Development Guide.

For further integration, you can customize the icon to change dynamically based on the state of the app. For example, a weather application icon can change based on the weather forecast — a sun to indicate a sunny forecast or rain drops to indicate a rainy forecast. Using a state type icon allows the user to see the most relevant information. If the user wants further details, they can simply click the icon to launch the app. This sort of customized icon is related to making your app proactive and notification-driven. For information about creating a dynamic icon, see the Proactive and notification-driven page.

Find out more

For more information about creating custom menu items, visit the following resources:

Customizing the Phone screen

You can integrate your app with the Phone app by customizing the call screens to display information from your app on the Incoming call and the Active call screens. For example, information that is provided by the Bookshelf app can be displayed when a BlackBerry device user receives a call from a fellow Bookshelf user.

You can customize the call screens on BlackBerry devices that are running BlackBerry Device Software 5.0 or later by using the Phone Screen API that is provided in the net.rim.blackberry.api.phone.phonegui package.

The device displays the content on the lower part of the call screen. If multiple apps provide content for a call screen, the device displays each app's content in sequence for approximately two seconds until the next call screen appears. For example, if you display content on the incoming call screen, the device displays the content until the user answers the call and the active call screen appears.


This screen shows a customized incoming call screen.

Code sample: Customizing the incoming call screen

public void callIncoming(int callId)
{
    ScreenModel screenModel = new ScreenModel(callId);
    PhoneScreen phoneScreenPortrait = screenModel.getPhoneScreen(PhoneScreen.PORTRAIT, PhoneScreen.INCOMING);
    LabelField labelField = new LabelField("Loaned book")
    {
        public void paint(Graphics g)
        {
            g.setColor(44504);
            super.paint(g);
        }
    };
    labelField.setFont(phoneScreenPortrait.getCallerInfoFont());
    phoneScreenPortrait.add(labelField);
    screenModel.sendAllDataToScreen();
}

Find out more

For more information about displaying content on the phone screen, visit the following resources:

Embedding UI components

There are a number of specialized UI components that core apps on the BlackBerry device use. You can integrate these UI components in your app to provide users with a familiar and seamless experience on their BlackBerry device. Below are some examples of UI components that you can integrate into your app:

Component

Description

AutoCompleteField

You can use the AutoCompleteField class to compare the text that a user types in the field against the items in a data source, and display the matches in a drop-down list below the field. The data source can retrieve information from other apps (for example, names from the Contacts application), or use customized information (for example, days of the week).

LocationPicker

You can use the LocationPicker class to give users the ability to select a location by using sources such as contacts from the Contacts application, GPS coordinates, recent locations, and suggestions from apps.

FilePicker

You can use the FilePicker class to provide users with the ability to select a file by navigating to a folder.

MapField

You can use the MapField class to embed a map in your app.

BrowserField

You can use the BrowserField class to embed web content in your app.

Media fields in javax.microedition.media and javax.microedition.media.control

You can use the media fields to embed media players and media recorders in your app by using the Mobile Media API (JSR 135).


This screen displays an autocomplete field.

Code sample: Creating an AutoCompleteField UI component

BasicFilteredList filterList = new BasicFilteredList();
String[] days = {"Fiction","Biography","History", "Non-fiction"};
filterList.addDataSet(1,days,"days",BasicFilteredList.COMPARISON_IGNORE_CASE);
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
add(new LabelField("Choose a book type:"));
add(autoCompleteField);