Service features

The Nokia Notifications Service API provides access to the Notification Server via an HTTP REST interface. Your service uses this interface to send notifications to your MIDlet.

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

1. Service credentials

Service ID and Service Secret are used to authenticate your service to the Notification Server (obtained from the Developer Console). All push notifications sent by the service are authenticated with digest authentication over HTTPS.

2. Notification content

All notifications sent using the Notification Server can include an optional customised payload of up to 1.5 kB. Format of the payload can be plain text, XML, image, binary etc.

3. Method of sending notification

Sending a notification using the unique Notification ID.
- The notifications can be sent to a single user or in bulk to multiple users. When sending notifications to a single user or in bulk, the Notification ID is used to specify the recipient(s) of the notifications.
  
  Note:
  The Notification ID must be retrieved by your MIDlet using a method in the Client API and then sent to your service.
Sending a notification using Publish.
- When using Publish, notifications are sent to all users of your service.

4. Real-time, and Store and Forward

The sending of notifications is on “best effort” basis. This means that the notifications are delivered, if the MIDlet is online and the network connection works. However, the Notification Server does not make guarantee on the delivery of the notifications.

Generally, notifications are pushed to MIDlets in real-time. However, it is possible to complement the real-time delivery with Store and Forward functionality, by using expires-at parameter. This is useful, for example, in a situation where a user has turned the notifications off for some time. In this case, a notification that is using Store and Forward functionality is stored on a server and delivered to the MIDlet once the user enables reception of notifications again. The maximum limit for the stored notifications is 5 notifications per user per MIDlet, and maximum time to store a notification is 14 days. If the storage time defined in the notification runs to end before the user comes online again, then the notification is deleted from the server without sending.

The following state diagram describes how Store and Forward functionality works in the case described above (user is offline when a notification is sent). Complementing the real-time delivery with Store and Forward functionality is especially useful if the network coverage is limited. It improves the delivery rate of the notifications, allowing the service to reach its users even if they tend to get disconnected from time to time. However, if user is continuously offline (HTTP status codes 201 and 204), the service should consider how long to keep on sending messages to such a user.