C/C++ Guides

Home

The Notification Library and API

Update: From MoSync 3.2.1 local notifications can be triggered on Android devices regardless of the running state of the application. Therefore, LocalNotification::setDisplayFlag() will have no effect and the behaviour will be consistent on both Android and iOS.

Use maTime() ( instead of maLocalTime() )  in conjunction with setFireDate() in order to schedule a local notification, as shown in the example below.

The MoSync Notifications Library provides a set of C++ classes and methods for handling both push notifications (coming from a service provider) and local notifications (originating from the device itself.) The Library is built on top of the MoSync Notifications API which provides a comprehensive set of C syscall functions.

For a list of the platforms supported by the MoSync Notifications Library and Notifications API, see Feature/Platform Support. (This API is used under-the-hood by the Wormhole Library's JavaScript Notification API.)

Platform differences

Taking into account that both Android and iOS handle notifications differently, there are some platform-specific usage requirements when handling notifications:

  • On iOS push notifications are handled by Apple Push Service, and on Android by Google C2DM Service, so the registration process is slightly different. On Android there is a Google account requirement in the registration process via registerPushNotification function: the accountID param. Is the ID of the account authorized to send messages to the application — typically the email address of an account set up by the application's developer.
  • Display flags are available on Android using the setDisplayFlag function, which may enable the notification to be shown even if the application is in foreground.

  • There are a couple of Android specific methods on local notifications:
    • setFlag to control how local notifications are shown/canceled.
    • setTickerText, setContentTitle that control the appearance of the notification.
    • vibration, sounds and LED patterns.
  • On iOS, the badge number of the application icon can be set.

Tutorials and examples

For step-by-step guide to creating mobile applications that use the Notifications Library, and API, see:

The Notification Library

The MoSync Notifications Library contains classes and methods for handling both local and push notifications.

Local notification classes and methods

Local notifications are encapsulated in objects of class type LocalNotification. The main methods on this class include:

  • LocalNotification() — the constructor, the minimum required to create a local notification object.
  • setFireDate — Set the date and time when the system should deliver the notification.  If this property is not explicitly set, then the local notification will be fired automatically.
  • setBadgeNumber — Set the number displayed on the application's icon badge.
  • setContentBody — Set the message displayed in the notification alert.
  • setContentTitle — Set the title that goes in the expanded entry of the notification.
  • setTickerText — Set the text that flows by in the status bar when the notification first activates.
  • setFlag — Set the NotificationFlag applied to the local notification.
  • setDisplayFlag — Set the NotificationDisplayFlag applied to the local notification. Note that regardless of this setting, the didReceiveLocalNotification callback will be made for each incoming notification.
  • setAlertAction — Set the title of the action button or slider.
  • setPlaySound — Enable/disable the sound played when an alert is displayed.
  • setSound — Set the sound to play when an alert is displayed. Could be ignored if using setPlaySound(false).
  • setVibrate — Enable/disable the the default vibration when an alert is displayed. By default, the vibration is disabled.  — If set to true, it will use the default notification vibrate. This will  ignore any given vibrate. Using phone vibration requires the VIBRATE permission.
  • setVibrateDuration — Set the vibration duration when an alert is displayed. This setting is ignored if setVibrate is disabled.
  • setFlashLights — Enable/Disable the default notification LED lights.
  • setFlashLightsPattern — Define your own color and pattern for the lights.

An application can add a local notification event listener by calling NotificationManager::addLocalNotificationListener.

The LocalNotificationListener class contains the virtual method:

  • didReceiveLocalNotification

The event listener can also be removed by calling NotificationManager::removeLocalNotificationListener.

An application can add a listener for push notifications by calling NotificationManager::addPushNotificationListener and of course, by implementing the listener’s methods.

The PushNotificationListener class contains the following virtual methods:

  • didReceivePushNotification
  • didApplicationRegistered
  • didApplicationUnregister
  • didFailedToRegister


Push notification classes and methods


PushNotification class objects should not be created by the user. Push notifications can only be received in the didReceivePushNotification callback.

PushNotification methods used for accessing the content of a received push notification include:

  • containsMessage — Checks if the push notification contains alert message.
  • getMessage — Get the alert message.
  • containsSoundFileName — Check if the push notification contains sound file name.
  • getSoundFileName — Get the sound file name.
  • containsIconBadgeNumber — Check if the push notification contains icon badge number.
  • getIconBadgeNumber — Get the application icon badge number.

Communications with the Notification API

The Notification API is handled through the singleton class NotificationManager via the functions:

  • scheduleLocalNotification — Schedules a local notification for delivery at its encapsulated date and time. By default, the notifications are displayed to the user only if the application is in background. But on Android you can configure this by calling setDisplayFlag.
  • unscheduleLocalNotification — Cancels the delivery of the specified scheduled local notification.
  • addLocalNotificationListener — Add an event listener for local notifications.
  • removeLocalNotificationListener — Remove the event listener for local notifications.
  • registerPushNotification — Registers the current application for receiving push notifications.
  • unregisterPushNotification — Unregister application for push notifications.
  • addPushNotificationListener — Add listener for push notifications received by this application.
  • removePushNotificationListener — Remove listener for push notifications received by this application.
  • setApplicationIconBadgeNumber — Set the number currently set as the badge of the application icon.
  • setPushNotificationsDisplayFlag — Set the display flags applied to the incoming push notifications. Note that regardless of this setting, the didReceivePushNotification callback will be made for each incoming notification.
  • setPushNotificationsTitle — Set the  message title in the notification area for incoming push notifications.
  • setPushNotificationsTickerText — Set the ticker text in the notification status bar for incoming push notifications.

More information on each of these functions can be found in the MoSync C/C++ API Reference.

Notification Syscalls API

Local notification syscalls

  • maNotificationLocalCreate  — Creates a new local notification object. If FIRE_DATE is not set, the default current time is applied.
  • maNotificationLocalSetProperty — Sets a local notification property.
  • maNotificationLocalDestroy — Destroys a local notification object, and clears it from the notifications list.
  • maNotificationLocalGetProperty — Retrieves a specified property from the given notification object.
  • maNotificationLocalSchedule — Schedules a local notification for delivery at its encapsulated date and time.
  • maNotificationLocalUnschedule — Cancels the delivery of the specified scheduled local notification. Calling this method dismisses the notification if  it is currently displaying an alert.

(Note: you have to set the FIRE property and then register the notification. If the fire value is not set the local notification is displayed immediately when maNotificationLocalRegister is called.)

Push notification syscalls

  • maNotificationPushRegister — Registers the current application for receiving push notifications. The application will receive an EVENT_TYPE_PUSH_NOTIFICATION_REGISTER after the registration is handled and the user may call maNotificationPushGetRegistration to get the results.
  • maNotificationPushGetRegistration — Retrieves  the latest registration response in a string: the registrationID if the registration was successfull, or the error messsage otherwise.
  • maNotificationPushUnregister — Unregisters an application for push notifications. Unregistration is also accomplished by un-installing the application. The EVENT_TYPE_PUSH_NOTIFICATION_UNREGISTER will be received on Android if it was successful.
  • maNotificationPushGetData — Fills the pushNotificationData struct with the values for a given push notification.
  • maNotificationSetIconBadge — Set the number currently set as the badge of the application icon in Springboard. Platform: iOS only. Set it to 0 to hide the badge number.
  • maNotificationGetIconBadge — Get the number currently set as the badge of the application icon. Platform: iOS only.  
  • maNotificationPushSetTickerText — Set the ticker text in the notification status bar for incoming push notifications. This call does not alter already received notifications. Ticker text: is the text that flows by in the status bar when the notification first activates. Platform: Android only.
  • maNotificationPushSetMessageTitle — Set the  message title in the notification area for incoming push notifications. This call does not alter already received notifications. Platform: Android only.
  • maNotificationPushSetDisplayFlag — Set the notification display flags applied to the incoming push notifications.
  • maNotificationPushDestroy — Destroy a push notification object.


Notification Events

  • EVENT_TYPE_LOCAL_NOTIFICATION — Sent when the application receives a local notification.
  • EVENT_TYPE_PUSH_NOTIFICATION_REGISTRATION — Sent when the application receives a registration result. The application tries to register to Apple Push Service, or Google C2DM Service, and the received result ( either success, either fail) is sending this event. After this event is received, get the result of the registration request by calling maNotificationPushGetRegistration.
  • EVENT_TYPE_PUSH_NOTIFICATION_UNREGISTRATION — Sent when the application receives an unregistration result. The application unregistered from Google C2DM Service, and will not receive anymore push messages. Platform: Android only.
  • EVENT_TYPE_PUSH_NOTIFICATION — Sent when the application receives a push notification.

 

Creating and firing off local notifications

Start by creating a new C++ NativeUI Project:

  1. Open the MoSync IDE and select File > New > Project.
  2. Select MoSync Project and click Next.
  3. Enter a name for your project and click Next.
  4. Select the MoSync NativeUI C++ Project template and click Finish. The template will open in the IDE.

Open the main.cpp file in the project, and add the #include directives for the local notification files and the Notification namespace:

#include <MAUtil/Moblet.h>
#include <IX_WIDGET.h>

#include <Notification/NotificationManager.h>
#include <Notification/LocalNotification.h>
#include <Notification/LocalNotificationListener.h>

using namespace MAUtil;
using namespace Notification;

Inside the Moblet constructor attach the listener. Also, create a local notification object and set the time when it should be delivered.

NativeUIMoblet()
{
createUI();
NotificationManager::getInstance()->addLocalNotificationListener(this);
LocalNotification* notification = new LocalNotification();

// Set fire date after 10 seconds.
int seconds = 10;
int secondsLocalTime = maTime();
int scheduleTime = secondsLocalTime + seconds;
tm fireDate;
split_time(scheduleTime, &fireDate);
notification->setFireDate(&fireDate);
// Set message body.
notification->setContentBody("My new message");
// Set some platform specific values.
if ( isAndroid() )
{
    // Set the vibration duration to 5seconds when an alert is displayed.
    notification->setVibrate(true);
    notification->setVibrateDuration(5);
    // Set notification title and ticker.
    notification->setContentTitle("My message title");
    notification->setTickertext("You gota message");
}
else
{
    // Set a badge number.
    notification->setBadgeNumber(6);
    // Set the title of the action button or slider.
    notification->setAlertAction("ok");
}
}

Finally, you can schedule for delivery the notification:

NotificationManager::getInstance()->scheduleLocalNotification(notification);

Now let’s implement listener’s methods:

virtual void didReceiveLocalNotification(LocalNotification& localNotification)
{
    maMessageBox("New local notification with the message", localNotification.getContentBody().c_str());
}

For receiving push notifications in your  application please see the Creating a push notification application section in the tutorial page.

MoSync SDK 3.3
Copyright © 2013 MoSync AB
www.mosync.com