Porting Google Cloud Messaging to Nokia Notifications

The Nokia Notifications API in Nokia X software platform provides a subset Google's Cloud to Device Messaging (C2DM) and Google Cloud Messaging (GCM) features. The API is very similar to GCM except for the namespace.

Feature comparison

Nokia Notifications API feature set matching the C2DM and GCM offering:

  • Client API:
    • Matching push notification APIs.
    • Intent based API to:
      • register/unregister in device to receive notifications, and
      • receive notifications with payload.
    • Nokia Notifications helper library to use the Intent based API.
      • Registering the application: com.nokia.pushnotifications.REGISTER
      • Unregistering the application: com.nokia.pushnotifications.UNREGISTER
      • Receiving registration ID: com.nokia.pushnotifications.intent.REGISTRATION
      • Receiving notifications with payload: com.nokia.pushnotifications.RECEIVE
  • Service API:
    • Support for 4 kB payload.
    • Storage for 100 non-delivered messages in server.
    • Support for RECEIVE intent with message_type "deleted_messages" to tell the client how far behind it is.
    • HTTP API that supports JSON and plain text.
    • dry_run parameter allowing developers to test their request without actually sending a message.

The following features are not supported by Nokia Notifications API:

  • Client API:
    • Receiving messages from multiple senders, e.g. a news application receiving messages from multiple sources.
    • Using one sender ID for multiple apps on the same device, which allows single service to send notifications to different apps.
  • Service API:
    • Service statistics for developer.
    • User specific notifications, which provides a mapping between a user and instances of an app running on multiple devices owned by the user.
    • There is no support for Cloud Connection Server (XMPP) for handling bi-directional messages from device to cloud.
    • Some optional server API parameters:
      • restricted_package_name: A string containing the package name of your application. When set, the messages will only be sent to registration IDs that match the package name.
      • collapse_key: For collapsing group of the notifications.
      • notification_key: For sending the notification to multiple devices of the one user.
      • delay_while_idle: To prevent the notification sending to the idle device. The notification is delivered when the device is active next time.

Differences in namespace

Table 1. General differences in namespace.

GCM Nokia Notifications
com.google.android.c2dm.* com.nokia.pushnotifications.*
com.google.android.gcm.* com.nokia.push.*
com.google.android.gms.gcm.GoogleCloudMessaging Not available yet

Table 2. Intent and permission names.

GCM Nokia Notifications
com.google.android.c2dm.intent.REGISTER com.nokia.pushnotifications.intent.REGISTER
com.google.android.c2dm.intent.UNREGISTER com.nokia.pushnotifications.intent.UNREGISTER
com.google.android.c2dm.intent.REGISTRATION com.nokia.pushnotifications.intent.REGISTRATION
com.google.android.c2dm.intent.RECEIVE com.nokia.pushnotifications.intent.RECEIVE
com.google.android.c2dm.permission.SEND com.nokia.pushnotifications.permission.SEND
com.google.android.c2dm.permission.RECEIVE com.nokia.pushnotifications.permission.RECEIVE

Porting options for the client app

Before you can start using Nokia Notifications API, you need to register a sender ID in Nokia Notifications developer console (https://console.push.nokia.com).

Porting your existing GCM application to use Nokia Notifications can be done by two different options:

  1. If your application utilises the GCM helper library (gcm.jar), you can take in use the Nokia Notifications helper library which implements a similar API. For the specific steps, see Porting an application that uses GCM helper library API.
  2. If your application utilises C2DM/GCM Intent API, you need to replace the namespaces of intent actions and permissions to match those defined in Nokia Notifications API. For the specific steps, see Porting an application that uses C2DM/GCM Intent API.

Alternatively, you can abstract the notifications specific code in your app or use an adaptive, dynamic approach to incorporate both Google services and Nokia Notifications in a single application. The latter method is covered in the co-development guide.

Regardless of the option you choose, any C2DM or GCM application that is modified to use Nokia Notifications needs the following changes:

  1. Change sender ID from Google API project number or account name to Nokia Notifications sender ID.
    • To acquire the Nokia Notifications sender ID you need a Nokia Developer Account to access the Nokia Notifications developer console.
  2. Make sure that application's own service knows how to send notifications to applications associated with a specific Nokia Notifications registration IDs.
    • Your service has to use the Nokia Notifications Server API to send push notifications to devices using Nokia Notifications, so you should either:
      • modify the service to only use the Nokia Notifications Service API, or
      • add some metadata to the registration ID so that the service knows which service each ID is associated with.

Changes to manifest file

The manifest file (AndroidManifest.xml) has to be always modified in order for your application to support Nokia Notifications. The required changes, however, are minimal. Note that the actual names of permissions and intent match, but only the namespace is different; you have to change all occurrences of com.google.android.c2dm to com.nokia.pushnotifications. Below is an example of the manifest file content before and after these changes.

GCM:

    <permission
        android:name="(your_application_package).permission.C2D_MESSAGE"
        android:protectionLevel="signature" />
    <uses-permission android:name="(your_application_package).permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    
    ...
    
    <application ... >
        <receiver
            android:name="com.google.android.gcm.GCMBroadcastReceiver"
            android:permission="com.google.android.c2dm.permission.SEND">
            <intent-filter>
                <!-- Receives the actual messages. -->
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <!-- Receives the registration id. -->
                <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
                ...
            </intent-filter>
        </receiver>
        
        <service android:name=".GCMIntentService" />
    </application>

Nokia Notifications:

    <permission
        android:name="(your_application_package).permission.C2D_MESSAGE"
        android:protectionLevel="signature" />
    <uses-permission android:name="(your_application_package).permission.C2D_MESSAGE" />
    <uses-permission android:name="com.nokia.pushnotifications.permission.RECEIVE" />
    
    ...
    
    <application ... >
        <receiver
            android:name="com.nokia.push.PushBroadcastReceiver"
            android:permission="com.nokia.pushnotifications.permission.SEND">
            <intent-filter>
                <!-- Receives the actual messages. -->
                <action android:name="com.nokia.pushnotifications.intent.RECEIVE" />
                <!-- Receives the registration id. -->
                <action android:name="com.nokia.pushnotifications.intent.REGISTRATION" />
                ...
            </intent-filter>
        </receiver>
        
        <service android:name=".PushIntentService" />
    </application>

Porting an application that uses GCM helper library API

By helper library we refer to the push.jar library package that encapsulates the helper methods enabling easy integration of notifications service into your app. For more information, see Helper library section in the Client API guide.

A sample app demonstrating this approach is provided by the SDK and is located in <android-sdk-path>\extras\nokia\nokia_x_services\samples\nna\NokiaNotificationsHelperLibrarySample.

Porting steps

The following changes are necessary to switch to use the Nokia Notifications helper library:

  1. Replace the GCM helper library, gcm.jar, with the Nokia Notifications helper library, push.jar. You can find the helper library at <android-sdk-path>\extras\nokia\nokia_x_services\libs\nna.

  2. Modify application manifest (AndroidManifest.xml) as shown in Changes to manifest file and make sure to:
    • Change all occurrences of com.google.android.gcm.GCM to com.nokia.push.Push. This changes helper library namespaces and class names to match those provided by the Nokia Notifications helper library.
    • Change all occurrences of .GCMIntentService to .PushIntentService. This changes the name of the application-specific subclass of GCMBaseIntentService if it has the default name .GCMIntentService. This change is not needed if you have defined a custom BroadcastReceiver that redefines the name of the subclass.
  3. Replace references to GCM library classes, methods, and constants with Nokia Notifications helper library equivalents (in application java source files).
    • Change all references of com.google.android.gcm.GCMRegistrar to com.nokia.push.PushRegistrar. The following methods defined under GCMRegistrar have different names under PushRegistrar, so references to them have to be changed:

      Old method (GCMRegistrar) New method (PushRegistrar)
      getGCMPreferences getPushPreferences
    • Change all references to com.google.android.gcm.GCMConstants to com.nokia.push.PushConstants. The following constants defined under GCMConstants have different names under PushConstants, so references to them have to be changed:

      Old constant (GCMConstants) New constant (PushConstants)
      INTENT_TO_GCM_REGISTRATION INTENT_TO_SERVICE_REGISTER
      INTENT_TO_GCM_UNREGISTRATION INTENT_TO_SERVICE_UNREGISTER
      INTENT_FROM_GCM_REGISTRATION_CALLBACK INTENT_FROM_SERVICE_REGISTER_RESULT
      INTENT_FROM_GCM_LIBRARY_RETRY INTENT_FROM_HELPER_RETRY
      INTENT_FROM_GCM_MESSAGE INTENT_FROM_SERVICE_MESSAGE
      PERMISSION_GCM_INTENTS PERMISSION_SERVICE_INTENTS

      The following errors defined under GCMConstants are not defined under PushConstants, so references to them have to be removed:

      ERROR_ACCOUNT_MISSING
      ERROR_AUTHENTICATION_FAILED
      ERROR_PHONE_REGISTRATION_ERROR
    • Change all references of com.google.android.gcm.GCMBroadcastReceiver to com.nokia.push.PushBroadcastReceiver. The following methods defined under GCMBroadcastReceiver have different names under PushBroadcastReceiver, so references to them have to be changed:

      Old method (GCMBroadcastReceiver) New method (PushBroadcastReceiver)
      getGCMIntentServiceClassName getPushIntentServiceClassName
    • Change all references of com.google.android.gcm.GCMBaseIntentService to com.nokia.push.PushBaseIntentService

      In addition, if the application-specific subclass of GCMBaseIntentService has the default name GCMIntentService, it needs to be renamed to PushIntentService, which is the default name used by the Nokia Notifications helper library. This change is not needed if you have defined a custom BroadcastReceiver that redefines the name of the subclass.

Verifying the device compatibility and checking the manifest

Verifying the device compatibility and checking the manifest follows the exact same API:

GCM:

    GCMRegistrar.checkDevice(Context);
    GCMRegistrar.checkManifest(Context);

Nokia Notifications:

    PushRegistrar.checkDevice(Context);
    PushRegistrar.checkManifest(Context);

Registering and unregistering to service

GCM:

    GCMRegistrar.register(Context, String); // String contains the sender ID
    GCMRegistrar.unregister(Context);

Nokia Notifications:

    PushRegistrar.register(Context, String); // String contains the sender ID
    PushRegistrar.unregister(Context);

The push intent service class implementation will receive the server responses. When using GCM API, the service class derives from GCMBaseIntentService, whereas with Nokia Notifications API the base class is PushBaseIntentService. Like with the rest of the API framework, the names of the methods match, e.g. the callback method for successful registration is the following in both API frameworks:

    @Override
    protected void onRegistered(Context context, String registrationId) {
        ...

Porting an application that uses C2DM/GCM Intent API (GCM helper library is not used)

Nokia Notifications provides a Client API similar to C2DM/GCM Intent API. Porting the application can be accomplished by replacing namespaces of intent actions and permissions so that they are compatible with Nokia Notifications. The following changes are necessary to switch to use Nokia Notifications Client API:

  1. Modify application manifest (AndroidManifest.xml) as shown in Changes to manifest file.

  2. Modify java source files.

  • Change all occurrences of com.google.android.c2dm to com.nokia.pushnotifications. This changes prefixes of intent actions and permissions to match those used by Nokia Notifications. Specifically, intent actions and permission names listed in table 2 need to be changed (if used).

  • It is recommended to remove the following error code strings since these are never returned by Nokia Notifications:

    AUTHENTICATION_FAILED
    ACCOUNT_MISSING
    PHONE_REGISTRATION_ERROR
  • Change the name of the service provider package to match Nokia Push Notifications service package:

    Old package (GCM) New package (Nokia Notifications)
    com.google.android.gsf com.nokia.pushnotifications.service

Using ready-made wrapper provided by a sample app

An example application, GCM wrapper sample, demonstrating this porting approach is available in GitHub and is also provided with the Nokia X services package, located in <android-sdk-path>\extras\nokia\nokia_x_services\samples\nna\NokiaNotificationsGcmWrapperSample. You can utilise the subpackage com.google.android.gcm which contains java source files which already contain the changes necessary to support Nokia Notifications API. This allows you to port your application with minimal changes to your code base.

Video: Porting to Nokia Notifications

The media player is loading...

Modifying an application that uses GoogleCloudMessaging API

This topic compares how the latest GoogleCloudMessaging API differs from the Nokia Notifications helper library.

Comparing GoogleCloudMessaging with Nokia Notifications helper library

GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) client API is a new client API from Google. We can compare how the Nokia Notifications helper library differs from the GoogleCloudMessaging:

  1. GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) register and unregister are simple synchronous operations, whereas with the Nokia Notifications helper library the app developer needs to define a broadcast receiver for register/unregister responses and handle them in an intent service.
  2. Your app needs to handle incoming com.google.android.c2dm.intent.RECEIVE intents directly. The Nokia Notifications helper library provides a base intent service class that decodes the intents received. The app derives an intent service from this base class and puts the handler code into various onXXX() methods.
  3. GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) does not provide any utilities for keeping track of registration ID or the app's own server registration state. The Nokia Notifications helper library provides these utilities, but the app is not forced to use them.
  4. GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) does not have any built-in retry mechanism for failed operations. The Nokia Notifications helper library can automatically retry certain recoverable errors with an exponential back-off.
  5. GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) has methods for sending upstream "device to cloud" messages. No such methods exist in the Nokia Notifications helper library.

Based on the above points, compared to the Nokia Notifications helper library, GoogleCloudMessaging (com.google.android.gms.gcm.GoogleCloudMessaging) is minimalistic and leaves the implementation of supporting functionality (registration state management, error and retry handling) completely to the app developer.

Modification steps

Currently there is no direct equivalent Nokia Notifications API for the latest GoogleCloudMessaging API. However, if you already have an application which is using latest GoogleCloudMessaging API, you can follow these steps to make it work on Nokia X devices.

Changes required in the manifest file

Ensure that the following changes are done to the AndroidManifest.xml file, which is similar to adding Nokia Notifications support to any new project.

  1. Define the following permissions:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    
    <permission android:name="APPLICATION_PACKAGE_NAME.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="APPLICATION_PACKAGE_NAME.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.nokia.pushnotifications.permission.RECEIVE" />

    android.permission.WAKE_LOCK is not mandatory, but is recommended to ensure that the push notifications are fully handled when the device is in deep sleep.

  2. Define the broadcast receiver for Nokia Notifications intents. The receiver class provided by the helper library will pass the intent to APPLICATION_PACKAGE_NAME.PushIntentService.

    <receiver
        android:name="com.nokia.push.PushBroadcastReceiver"
        android:permission="com.nokia.pushnotifications.permission.SEND">
    
        <intent-filter>
            <action android:name="com.nokia.pushnotifications.intent.RECEIVE" />
            <action android:name="com.nokia.pushnotifications.intent.REGISTRATION" />
            <category android:name="APPLICATION_PACKAGE_NAME" />
        </intent-filter>
    
    </receiver>
  3. Define an application-specific service that is a subclass of com.nokia.push.PushBaseIntentService. This service will handle received messages. By default, the service must be named PushIntentService, unless the application uses a custom BroadcastReceiver that redefines its name.

    <service android:name="APPLICATION_PACKAGE_NAME.PushIntentService" />

Changes needed in the Java source code

  1. Check the availability of Nokia Notifications at application startup using com.nokia.push.PushRegistrar.checkDevice(). This method throws an exception, if the Nokia Notifications service is not available on the device. If Nokia Notifications is not available, the app could either try to fall back to using other push notification mechanism or report an error to user (if the app simply cannot be run without Nokia Notifications).
  2. Create the APPLICATION_PACKAGE_NAME.PushIntentService class that extends com.nokia.push.PushBaseIntentService, overriding the following methods to handle responses from Nokia Notifications:
    • onRegistered
    • onUnregistered
    • onMessage
    • onDeletedMessages
    • onError
    • onRecoverableError

    Remember to return false from onRecoverableError to disable the automatic retry functionality (since GCM app should have own retry mechanism already).

    Additional implementation tips:

    • Code that handles intents with message type GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE can often be directly copied into onMessage.
    • Code that handles intents with message type GoogleCloudMessaging.MESSAGE_TYPE_DELETED can possibly be reused in onDeletedMessages. However, you should be aware that the semantics of these notifications are a bit different: GoogleCloudMessaging.MESSAGE_TYPE_DELETED means that the server deleted some pending messages because they were collapsible, whereas onDeletedMessages means that the server deleted some pending messages because the device was idle.
    • Code in the onXXX handler method is protected by a wakelock acquired by the PushBaseIntentService class, but any asynchronous tasks initiated from within those methods must acquire their own wakelock before the original handler method returns.
    • Implementation of onRegistered/onUnregistered/onError/onRecoverableError depends on how you plan to handle porting of register/unregister, see the following step.
  3. Replace calls to GoogleCloudMessaging#register/unregister with calls to com.nokia.push.PushRegistrar#register/unregister. Since response to the latter is not synchronous, but is instead received asynchronously using APPLICATION_PACKAGE_NAME.PushIntentService#onRegistered/onUnregistered/onError/onRecoverableError, this will likely require a bit of refactoring.

    One alternative to this is to emulate a synchronous call by waiting on a response object after the register/unregister call. Then you can make the onRegistered/onUnregistered/onError/onRecoverableError handlers fill up that response object and call notify on it.

  4. Any functionality that depends on GCM device-to-cloud messaging must be disabled or re-implemented using a different mechanism.

Porting the server side implementation

Porting the server implementation is quite straightforward. The minimum set of changes include:

  • Changing the API key and
  • URI to https://nnapi.ovi.com/nnapi/2.0/send

For more information, see the Nokia Notifications Service API guide.


Last updated 12 August 2014

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×