Integrated

An important goal for your Super App is to make it work seamlessly with other applications on the BlackBerry® device. BlackBerry device users want a natural experience, where the flow between your application and other applications is seamless and easy to use. They likely aren't concerned with what happens behind the scenes, and many users don't have the time or patience to ramp up and learn the details of a new application. Users want your app to work, and they'd like it to integrate with the applications they use the most. By integrating with core applications and third-party applications, you can provide a seamless and natural experience for the user.

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

What are the benefits of integrating with other applications?

  • Use what's already built. You can use the existing features and functions of core applications and third-party applications 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 application because it's integrated with applications 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 application is already part of a user's routine, by integrating with that application, you can provide consistent behaviors and essential features that can also become part of the user's routine.

Approaches to integrating your application

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

Approach

Examples

Invoke an application and pass information to the application.

  • When a user selects the address of a bookstore in the Contacts application, launch a turn-by-turn navigation application to provide directions to the associated address.
  • While listening to a song on a radio application, launch another application that provides the option to purchase the song.

Integrate with existing or new content handlers.

  • When a user selects a link for an audio book, launch the media player to play the audio book file.
  • When a user receives a Microsoft® Word document, open the document by using the Documents To Go® application.

Integrate directly into an application by

  • Creating custom menu items
  • Embedding UI components in core applications
  • Adding custom UI fields
  • Add a custom menu item in the Calendar application that can open a meeting planner application.
  • Display a custom icon on the Home screen that changes based on the local weather forecast.
  • Embed a map that displays bookstore locations that stock the recommended book.

Integrating by invoking a core application

You can provide an integrated experience for your users by invoking a core application from your application and passing data to the core application. For example, in the Bookshelf application, a BlackBerry® device user can indicate that a book is loaned by clicking a menu item, such as Loan, which launches the Contacts application and retrieves contact information. From the Contacts application, the user can return to the Bookshelf application 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 applications and pass data to those applications. Core applications that can be invoked include Contacts, Calculator, Calendar, Camera, BlackBerry® Maps, MemoPad, Messages, Phone, Search, and Tasks.

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

Code sample: Invoking the Phone application

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 application and return to your application by using menu items. For more information about menu items, see Adding custom menu items.

Find out more

For more information about invoking applications, visit the following resources:

Handling content

Another approach to creating a seamless user experience is to make sure your application 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 applications to integrate with and use functionality in third-party and core applications that use these APIs. For example, DataViz®, in the Documents To Go® applications, use the Content Handler APIs to register their applications as the content handlers for various document types. This suite of applications that is preloaded on most BlackBerry® devices also provides handles to allow third-party applications to invoke the Documents To Go applications with the supported document types. For example, your application 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 application 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 application that is a content handler, you must register the application with the Registry API by using a unique ID. As part of the registration, you also specify the file types that the application can handle along with the actions that it supports for those files types. For example, you can register an application to print files of a specified type. Once your application is registered as a content handler, other applications 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 application 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 application 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 application may also supply arguments and data, and specify whether a response is required. To invoke a core application that is a content handler, you can use the net.rim.device.api.content.BlackBerryContentHandler class, which provides IDs for all core application 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 application with core applications, you can add a custom menu item. By adding custom menu items in core applications, you can provide a seamless experience for the BlackBerry® device user, where they can launch your application from another application 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 application 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 applications 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 application 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 applications.

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 application passes a context object to your application. The context that is returned depends on the core application 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 application

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, visit the following resources:

Adding application icons

The Home screen of the BlackBerry® device is the most visible and most accessed area for the BlackBerry device user. You can provide quick and easy access to your application by adding an icon to the Home screen. When the user clicks the icon, your application 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 application. 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 application proactive and notification-driven. For information about creating a dynamic icon, see the Proactive and notification-driven chapter.

Find out more

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

Customizing the Phone screen

You can integrate your application with the Phone application by customizing the call screens to display information from your application on the Incoming call and the Active call screens. For example, information that is provided by the Bookshelf application 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 applications provide content for a call screen, the device displays each application'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 applications on the BlackBerry® device use. You can integrate these UI components in your application 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 application:

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 applications (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 applications.

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 application.

BrowserField

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

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 application 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);
Previous topic: Create a pop-up menu

Was this information helpful? Send us your comments.