Getting started with Nokia Notifications API

Prerequisites

Features

Loading and using Nokia Notifications Client API

Load the session by calling the NotificationSessionFactory and give the application identity.

private NotificationSession session;
session = NotificationSessionFactory.openSession(midlet, "example.com", "com.example", this);

Sending and receiving notifications

When using the Nokia Notifications API, the MIDlet needs to have an associated notifications service. This notifications service initiates the actual message (notification) delivery, and the Nokia Notifications Client API adds support to the MIDlet to receive notifications. The notifications service and the MIDlet do not communicate directly. Instead, they use the Nokia Notifications API for accessing the Nokia Notification Server as follows:

• The notifications service uses the Nokia Notifications Service API (REST API) to access the Nokia Notification Server, and to send notifications to the MIDlet on the device.

• The MIDlet uses the Nokia Notifications Client API to access the Nokia Notification Server, and receive notifications from the notifications service.

Lifecycle of a notification

A typical lifecycle of a notification is as follows:

1. The MIDlet calls the Nokia Notifications Client API to register the MIDlet to receive notifications. The MIDlet uses the application jad file's MIDlet-Name identifier parameter to identify the MIDlet name that is registered. Before the notifications service can use this identifier, the notifications service has to be registered as a Service ID on the Nokia Developer Console. In the diagram the identifier value is com.example. Once the registration is successful, the MIDlet has to request a Notification ID.

2. The MIDlet has to send the Notification ID, retrieved from the Nokia Notification Server, to the notifications service that will be using the Nokia Notifications Service API (REST API) to send notifications. The notifications service is named in the diagram as example.com. The MIDlet developer can use any language to develop the notifications service sending the notifications. There are several ways to submit the Notification ID to the notifications service, and the developer has to select the preferred way to do it.

3. The notifications service sends the notification to the Nokia Notification Server using the REST API. The Notification ID defines the address of the receiving MIDlet instance. It is possible to send notifications to multiple Midlets with one REST API call.

4. The Nokia Notification Server sends the notification to the MIDlet instance with the Notification ID given as address in the REST API call.

Nokia Notification indicators and settings

Notification indicators

When a notification is received in the device:

• A Notification banner appears as a box on the top of the screen. It consists of the following elements:

  • The icon of the MIDlet that the notification was sent to. The icon is read from the MIDlet jad parameter MIDlet-Icon that is propagated to the mobile operating system when the MIDlet is installed.

  • The display name of the MIDlet that the notification was sent to. The display name is read from jad parameter MIDlet-Name value of the MIDlet.

  • The number of received notifications or a notification title. When a notification is sent, it is possible to include a title attribute in the notification. If the title attribute exists in the notification, the value of the title is shown. If the title attribute is not present, the number of received notifications is shown. The number of received notifications indicates the number of unread notifications that are waiting for the MIDlet to read them by using the Nokia Notifications Client API.

• A Notification tone is played, if selected in the Notification tone under Settings, and if the attribute is set in the message when sending using the REST API.

Notification panel

After the notification has been received and the banner is shown, the notification is moved to the notification panel. Each MIDlet receiving notifications has only one item in the notification panel. The item shows the MIDlet icon, the display name, the title of the latest received notification, and the number of notifications waiting in the device buffer for delivery to the receiving MIDlet.

Notification settings

The notifications page includes a list of MIDlets that use the Nokia Notifications Client API. Each MIDlet has a switch that can be enabled or disabled. When the application switch is enabled for the MIDlet, it can receive notifications in the device, and when the application switch is disabled for the MIDlet, it cannot receive notifications in the device. The REST API creates a queue for sent notifications. Even if the MIDlet switch is disabled, the five latest notifications are stored on the Nokia Notification Server, to be delivered when the MIDlet is enabled to receive notifications.

Internet connection

The Nokia Notifications Client API establishes an Internet connection, on behalf of the MIDlet, and maintains the Internet connection between the device and Nokia Notification Server. The MIDlet is informed of the state changes.

Environment Selector

The Environment Selector is a developer tool with which the developer can set the Notification Enabler to point to the sandbox, the production or the Chinese production environment.