Add notification support to notifications service

The REST API

The notifications service can be created with any scripting or programming language. Once the notifications service is created, the Nokia Notifications Service API (REST API) is used to add notification support to it. The REST API allows notifications services to push notifications to the Nokia Notification Server.

The notifications service uses the REST API to send notifications to the MIDlet via the Nokia Notification Server, as shown in the following diagram.

To send a notification, the notifications service must provide the following information to the Nokia Notification Server:

Service credentials
Notification
Recipient

Service Credentials

The notifications service must authenticate with the Nokia Notification Server. This is accomplished by supplying the Service ID and Service Secret (which are obtained during the registration and are visible in the Nokia Developer Console) to the Nokia Notification Server. The notifications service has a specific shared secret for all the active environments. All notifications sent by the notifications service are authenticated with the digest authentication over HTTPS.

Notification

The notification can include content of any type (for example text or image), but it cannot be larger than 1.5 kB.

Recipient

The Nokia Notifications Service API (REST API) supports the following methods for specifying the recipient of the notifications:

Sending a notification to a single user, using the unique Notification ID provided by the MIDlet.
Sending notifications in bulk, using the unique Notification ID provided by the MIDlet.

Note: Notification ID is used for handling the device user identity. The Notification ID is retrieved on the device using a method in the

Nokia Notifications Client API, and then sent to the notifications service. The REST API also supports sending notifications using the User ID and Application ID of the recipient. This method is however supported only for devices on earlier platform versions, and for testing purposes. Further, using the publish method, notifications can be sent to all registered MIDlets that are online.

Using the Notification ID

The Notification ID is unique per MIDlet and user. It provides additional privacy to the MIDlet users by allowing the notifications service to deliver notifications to the MIDlet users with just the Notification ID. The developer must ensure the MIDlet shares the Notification ID with the notifications service, for receiving notifications.

The following diagram shows the implementation in the MIDlet.

The Notification ID is requested by the MIDlet, from the Nokia Notification Server, at run time (step 1). The MIDlet then sends the Notification ID to the notifications service (step 2), so it can be used as a private delivery method for notifications (steps 3 and 4).

Note: The sharing of the Notification ID takes place outside of the Notification Service connection. The Notification ID is typically between 100 and 200 Bytes in length, but it may be longer in some cases, and therefore the developer should reserve at least 512B for storing it. The value of the Notification ID is the same in the sandbox and the production environments, but is different in the Chinese production environment.

Store and forward server functionality

Store and forward is a server functionality that stores notifications targeted to a specific user until that user comes online again.

A notification is stored for later delivery if the MIDlet is offline i.e. not registered to receive notifications currently. When the Nokia Notification Server notices that the MIDlet is not online then the notification is stored if the expires-at parameter of the notification has a value greater than 0. From the viewpoint of the Nokia Notification Server, the MIDlet is offline after it has unregistered itself successfully. If the time defined in the notification message, the expires-at parameter, runs to end then the Nokia Notification Server deletes the stored notification automatically and it will never be sent.
Maximum limit for the stored notifications is 5 notifications per user per MIDlet.
Maximum time to store a notification is 14 days (defined by the expires-at parameter).
Neither the Nokia Notification Server nor the Notification Enabler does return information if the notification was received by the device. If this kind of reporting is needed by the notifications service then the MIDlet needs to send the receipt directly to the notifications service. This is up to implementation and not part of the Nokia Notifications API as such.

More information

The developer needs to consider what is notifications service specific and what is not. For more information see Key considerations for Nokia Notifications API.