rtht
- 1. F O R U M N O K I A Notifications API White Paper
- 2. Forum.Nokia.com Copyright © 2010 Nokia Corporation. All rights reserved. Nokia and Forum Nokia are trademarks or registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. Disclaimer The information in this document is provided “as is,” with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. This document is provided for informational purposes only. Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights. Nokia Corporation retains the right to make changes to this document at any time, without notice. License A license is hereby granted to download and print a copy of this document for personal use only. No other license to any other intellectual property rights is granted herein. Notifications API 2
- 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