3. Forum.Nokia.com
Contents
1 Notifications API overview ....................................................................................................................................................... 4
2 The challenge: building efficient notifications .................................................................................................................. 4
2.1 The balancing act...................................................................................................................................................... 4
3 The solution ............................................................................................................................................................................. 5
4 Value across the entire ecosystem ........................................................................................................................................ 5
4.1 Benefits for developers ........................................................................................................................................... 5
4.2 Benefits for consumers ........................................................................................................................................... 5
4.3 Benefits for operators ............................................................................................................................................. 6
5 High-level design ........................................................................................................................................................................ 6
5.1 Service API .................................................................................................................................................................. 6
5.2 Client API ..................................................................................................................................................................... 6
5.3 Typical lifecycle of a notification .......................................................................................................................... 7
5.4 Limitless design possibilities ................................................................................................................................ 8
5.5 Sending notifications .............................................................................................................................................. 8
6 Receiving notifications ............................................................................................................................................................. 9
6.1 Always-on connection ............................................................................................................................................. 10
6.2 Notification content ................................................................................................................................................. 10
6 Security ............................................................................................................................................................................. 11
7 Getting started............................................................................................................................................................................. 11
7.1 Forum Nokia account .............................................................................................................................................. 11
7.2 Register to participate in Notifications API Technology Preview ............................................................. 11
7.3 Notifications API Project Site: documentation, files, and libraries ............................................................ 11
7.4 Developer Console .................................................................................................................................................... 12
8 Summary ............................................................................................................................................................................. 12
Notifications API 3
4. Forum.Nokia.com
1 Notifications API overview
The Notifications API, available using the Nokia Qt SDK, makes it easy to add real-time push
notifications to your applications. With up-to-the-moment, efficient delivery of lightweight
notifications, your application stays at the forefront of consumers' attention. At the same time, your
mobile application will be able to optimize bandwidth and battery use, giving your customers
increased functionality without adversely impacting the device or data plans.
2 The challenge: building efficient notifications
Today mobile user expects immediate access to fresh, relevant data. Fresh data brings the application
to the users’ attention, encouraging them to engage and interact with the application more
frequently. This continuous user engagement makes a mobile application sticky, but only if it’s
delivered along with a great user experience, as in the following examples:
A navigation application that alerts mobile device users to changes in optimal routes and even
updates the weather conditions for their destinations.
A music store that suggests music play lists based on the user’s social network favorites.
A news application that sends the latest headlines as soon as they’re available.
2.1 The balancing act
Balancing the user experience with battery and data use along with design complexity can be
challenging for developers who want to deliver engaging mobile applications with notifications. Too
often, building frequent data updates into an application has negative implications for the overall
device experience. Polling mechanisms cause an application to use the network unnecessarily to
query the cloud even when no new data is available. This creates unnecessary bandwidth use,
connectivity cost, and battery drain – an unacceptable experience for the user. Push solutions can be a
more efficient option, though often developers must design different versions of their applications to
ensure they work across the wide variety of networks, resulting in extra development costs and
inefficiency. Further, some notifications mechanisms use a “store and forward” model with timed
pushes or pulls, where notifications are stored on a server until they are all delivered to the
application at a set time. In this situation, users may not always have fresh and up-to-the-moment
content unless developers can override store and forward to ensure real-time delivery.
Developers must manage design and development complexity as they write and maintain code that
delivers notifications functionality, especially when supporting multiple versions of an application.
Without intuitive tools for adding notifications to applications, this can be time consuming and costly.
Additionally, if platform and network providers restrict the notifications functionality and formats,
including how notifications can be sent to applications and devices in different activity states,
developers face further design challenges.
Notifications API 4
5. Forum.Nokia.com
3 The solution
Using the Notifications API, applications access Nokia-hosted notifications service, a shared persistent
connection that’s optimized to assure lightweight bandwidth use. Available from Forum Nokia as part
of Nokia Qt SDK the Notifications API includes a Service API for pushing notifications and a Client API
for receiving notifications.
Now developers can add push notifications to applications in a matter of hours – and the same code
runs on supported Symbian and MeeGo devices across any network. Prebuilt notification UI screens
are available to quickly and easily add notifications to applications. Or developers can create a
completely customized notification experience – they have the flexibility to decide how to design and
deliver notifications with custom payloads of up to 1.5 KB in any format, including text, xml, images,
and binary.
With the service enabled, Nokia devices don’t need to constantly poll or maintain multiple connections
across the network, saving both bandwidth and battery use. Notifications are pushed the moment
they’re available, whether the application is in the foreground, in the background, or not running.
4 Value across the entire ecosystem
The Notifications API benefits everyone involved in the development, distribution, and consumption of
mobile applications.
4.1 Benefits for developers
The Notifications API gives developers a way to differentiate applications so they can more easily
penetrate the worldwide market of Symbian and MeeGo mobile users. With elements of the
Notifications API, notifications can be quickly and easily customized bringing applications to the
forefront of consumers’ attention. By accessing the Nokia-hosted infrastructure developers can focus
attention entirely on building a unique experience that delights users and stands out in a competitive
environment.
4.2 Benefits for consumers
The top applications demonstrate that consumers love real-time information on their devices in every
type of app – games, news, maps, music, messaging. The top consumer complaints with applications
are high data charges and battery drain. The network and battery efficiencies experienced through
Notifications API 5
6. Forum.Nokia.com
the Notifications API ensure that users can enjoy a rich application experience with no adverse impact
on device or data plans.
4.3 Benefits for operators
The operators who are watching the ever-increasing amount of data consume bandwidth on their
networks are feeling the impact of the proliferation of smart phone applications perhaps most
acutely. At the same time, operators are in a position to benefit from the increase in application sales
through their application storefronts. With the Notifications API providing an efficient notification
traffic model for developers, operators can continue to push the sales of applications and see reduced
traffic on their networks.
5 High-level design
The Notifications API exposes two separate interfaces for developers to integrate: a Service API and a
Client API.
5.1 Service API
The Service API provides access to the notifications service via an HTTP REST interface. The application
server should use this interface to send notifications to your applications running on a user’s device.
5.2 Client API
The Client API resides on a Nokia device and allows applications on the device to register and receive
notifications. The Client API is available for the Nokia Qt SDK published by Forum Nokia. A Java SDK–
compatible version is planned for the near future.
Notifications API 6
7. Forum.Nokia.com
5.3 Typical lifecycle of a notification
As illustrated in the diagram below, before an application can receive notifications, it must register
with the notifications service and request a notification ID. The notification ID uniquely identifies both
the end user and the target application and is used by the notifications service to properly route
notifications.
The application should then share this notification ID with its respective application server so the
application server knows how to address the correct recipient (the intended user and application)
when sending a notification. Developers needs to be sure that the application and the application
server share the notification ID provided by the notifications service. ID sharing takes place outside
of the notifications service connection. Once an application is properly registered and the recipient’s
notification ID has been shared with the application server, the server can start sending notifications.
Notifications API 7
8. Forum.Nokia.com
5.4 Limitless design possibilities
Using the prebuilt notifications UI screens, developers can quickly and easily add notifications to
applications. They also have the flexibility to design and deliver notifications by creating a completely
customized notification experience.
With this service, notifications can be sent to the application regardless of the application's activity
state. Table 1 below illustrates the many options developers can use to interact with the application
and stimulate user engagement. For example, a notification can update an active application in real-
time, or it can trigger the application to wake-up when it’s not in use. Notifications can be presented
as an alert using the Notifications UI. Or a notification can initiate more sophisticated updates and
changes, either as part of the active UI or silently in the background – giving limitless design
possibilities.
Active Background Off
Update in foreground •
Update in background • •*
Present in background • •*
Use notification UI •
*Notification first triggers application launch
Table 1: Design options
5.5 Sending notifications
Notifications generated by a service’s application server should be sent to the notifications service
through its exposed HTTP REST Service API. The notifications service then delivers received
notifications to the recipient – specified by the notification ID – over the persistent connection
established between the device and the notifications service.
The sending of notifications is on a “best effort” basis. The infrastructure doesn’t provide
acknowledgement of successful notifications deliveries or of delivery failures caused by dropped
connections or lost packets.
In the future, the Notifications API may include message limits on a per service/application basis.
Notifications API 8
9. Forum.Nokia.com
6 Receiving notifications
Once a notification is received on a user’s device, it will be delivered to the appropriate application
through the Notifications Client API. Delivery can occur regardless of the current state of the target
application, whether it’s active, in the background, or even if it isn’t running, in which case it can be
woken up and launched.
Figure 1: Receiving notifications: foreground app updated
Figure 2: Receiving notifications: waking up an app from off to background
Notifications API 9
10. Forum.Nokia.com
Figure 3: Receiving notifications: notification stored in folder
There may be times when a user does not want to receive notifications, for example, at a certain
time of day or in a specific location. Just as the Notifications API allows applications to register for
notifications, the API also allows an application to unregister for notifications to prevent delivery.
Developers will need to include a setting in their applications so that users can enable or disable
notifications as needed.
6.1 Always-on connection
The Notifications API enables access to an always-on connection that’s shared between any
applications on the device that use the API – regardless of the developer. A shared connection means
that additional applications don’t generate additional radio traffic overhead.
Using a dynamic keep-alive message interval allows the connection to be further optimized for battery
consumption and data traffic. The ping interval used to maintain the persistent connection is tuned on
a per network basis so that, regardless of the user’s location and network, the frequency of pings is
minimized as set by parameters of the user’s current network. In addition to the obvious savings in
data traffic, sending fewer pings reduces radio and battery use.
6.2 Notification content
All notifications sent using the notifications service can include an optional customized payload of
up to 1.5 KB. While the intent of the Notifications API is to allow developers to send “lightweight”
notifications that provide context to applications rather than content, it’s up to developer to decide
how to use notifications, what to include in the payload, and what behavior that notification triggers.
There are no restrictions on the format of the payload; they can be plain text, XML, binary, and so on.
Notification messages are compressed using a Zlib compression algorithm, which further reduces the
amount of data consumed by notifications sent to the device.
Notifications API 10
11. Forum.Nokia.com
6.3 Security
All connections to the notifications service are secured via SSL: both the persistent connection from
device to the notifications service and the HTTP connection from application servers to the service. In
addition, the HTTP REST API requires a service secret to be included in all requests to ensure that all
notifications come from authenticated and authorized sources.
As there are no format payload limitations, further security can be added by encrypting any payload
transmitted through the notifications service at the application level.
7 Getting started
If you are a developer interested in adding notifications to your MeeGo or Symbian application,
getting started with the Notifications API is easy. Just follow the instructions below:
7.1 Forum Nokia account
The first step for gaining access to the Notifications API is to become a Forum Nokia member. If you’re
not a member already, visit the main page of the Forum Nokia Website to join:
www.forum.nokia.com/
7.2 Notifications API Project Site: DevKit, documentation, files, and libraries
You can access the Notifications API Project site and Developer Console, DevKit, documentation, case
studies, sample code, and more at the Forum Nokia Notifications API project site:
https://projects.forum.nokia.com/notificationsapi
Notifications API 11
12. Forum.Nokia.com
7.3 Developer Console
Forum Nokia members can then provision themselves for the service through the Notifications API
Developer Console. From the Developer Console, developers can request an application ID, a service ID,
and a service secret for access to the Notifications API. The returned application ID and service ID will
always be identical. The service ID and service secret are to be included by the application server when
sending requests to the HTTP REST Service API. The application ID, which will be the same value as the
service ID, is to be included by the device application when registering for notifications via the Client
API.
7.4 Testing and Publication
Now that you have added notification support to your service and your client application, you are
ready to send notifications! Nokia provides two environments for running your service and
application:
Sandbox environment: Use the Nokia-hosted sandbox environment to develop and test your
application. In this environment, a service can send notifications to client applications as if in a
production environment.
Production environment: When your service is tested and ready to be launched commercially, it can be
deployed in the Nokia-hosted production environment. Publishing your service means that its Service
ID is registered in the Ovi Notifications production environment, and that your service connects to the
production server address.
Note that a service must have been tested in the sandbox environment for at least five days before a
request can be made to have it deployed in the production environment. Now your application is
ready for distribution in the Ovi Store.
8 Summary
For developers, users, and network operators alike, the Notifications API provides increased
functionality and value without added expenses or overhead. The Notifications API lets developers
easily deliver a more engaging and “sticky” user experience on supported MeeGo and Symbian
devices. With an optimized, shared connection, users receive notifications across all their applications
without excessive battery drain or network usage. And operators can rest assured that no “bad
citizens” are generating unnecessarily heavy traffic across their networks.
The Notifications API offers unlimited possibilities for design, development, deployment and use.
Applications have access to notifications at all times, across all networks, and developers can use
notifications in whatever way they want to trigger whatever behavior they want in their applications.
The Notifications API offers limitless opportunity for adding notifications to applications, leaving
Notifications API 12
13. Forum.Nokia.com
creativity in the hands – and minds – of developers and providing Nokia users with an attractive user
experience complete with immediate access to fresh, relevant data.
Notifications API 13
