Using Notifications

Go Up to Using the RTL in Multi-Device Applications

Notifications are messages that the applications send to communicate information or alert about something.

Note: This topic is about local notifications, which are the notifications that the device applications send; for remote notification see Push Notifications.

RAD Studio provides the TNotificationCenter component to manage multi-device notifications. The notification center, allows you to send messages from a running applications. Applications can use the notifications to inform the user about something.

The TNotification component is the message that the application sends to the notification center to be displayed in the designated notification area according to the platform.

You can create notifications for Windows using VCL, or for your Multi-Device applications using FireMonkey.

Notifications Support per Platform

Item	Windows	OS X	iOS	Android
Platform Support	Windows 10 and Windows 8	10.8+
Name of Notification Area	Action Center	Notification Center	Notification Center	Notification Drawer
TNotification
TNotification.Name
TNotification.AlertBody			Mandatory
TNotification.Title		If no title, app name is used as title.	Not supported. App name used as title.	If no title, app name is used as title.
TNotification.FireDate	Not supported.
TNotification.Number	Not supported.	Not supported.	Sets the badge number.
TNotification.EnableSound	Not supported. Sound always enabled.
TNotification.AlertAction	Not supported.			Not supported.
TNotification.HasAction	Not supported.			Not supported.
TNotification.RepeatInterval	Not supported.
TCustomNotificationCenter
TCustomNotificationCenter.ApplicationIconBadgeNumber	Not supported.	Not supported. See OS X Badge Sample.		Not supported.
TCustomNotificationCenter.ScheduleNotification	Not supported.
TCustomNotificationCenter.PresentNotification

Windows Notifications

Toast notifications are compatible with the following versions of Windows:

• Windows 8: Windows 8 displays the notifications for a short period of time, after this, the user does not have any further access to the notifications.
• Windows 10: Windows 10 displays the notifications for a short period of time, after this, the notifications are available in the Action Center.

To access the Action Center to view the notifications, click the Action Center icon available on the taskbar. The icon changes depending on whether there are notifications pending or not:

Windows 10 Action Center Icon

Notifications Pending	No Notifications Pending

OS X Notifications

OS X supports notifications since version 10.8. For further information about OS X, see Using the Mac OS X Notification Center.

iOS Notifications

Notification Permissions

You need to add notification permissions to your application to use notifications in iOS. You need to ensure that the value of the key FMLocalNotificationPermission is set to true. Then, RAD Studio adds the appropriate key and value pair in the Info.plist file of your project.

To set FMLocalNotificationPermission to true:

1. Go to Project > Options > Version Info.
2. Select the appropriate iOS target platform.
3. In the key/value list, set the value of FMLocalNotificationPermission to true.

Notification Alert

iOS allows the user to set whether the notifications of an app is displayed as a banner or as an alert. Banners are displayed in the screen for a short period of time, while Alerts remain in the screen until the user interacts with the Alert.

To display the notifications as an alert, the end user has to go to the Notifications Settings of the application in the iOS device, and change the Alert Style when Unlocked settings to Alerts.

Creating Notifications

The TNotification class is used to create notification messages. You need the TNotificationCenter component to manage one or several TNotification instances.

After you have a TNotificationCenter component on your form, you can declare a TNotification variable, and call the CreateNotification method to create the notification.

Delphi:

MyNotification:= NotificationCenter1.CreateNotification;

C++:

TNotification *MyNotification = NotificationCenter1->CreateNotification();

After creating the notification, we recommend that you set at least the following fields:

• Name: with the unique name to identify your notification.
• AlertBody: with the text of the notification. The AlertBody filed is mandatory in iOS

You can manage other settings for your notifications:

• Title: with the title of the notification. iOS is not compatible with the Title field; iOS always displays the app name as title.

• Number: use this field to update the notification number in Android or the application badge number in iOS.

• ApplicationIconBadgeNumber: use this property to update the application badge number in iOS.

iOS Badge Number	Android Notification Number

Firing Notifications

FireDate is used to set the date and time when the notification is going to be fired.

As regarding the time to fire the notification, you can create two types of notifications.

• Immediate Notifications
• Scheduled Notifications

Immediate Notifications

By default, FireDate is set to Now, so if you do not change the value of FireDate, the notification is fired immediately.

Scheduled Notifications

Notifications can be scheduled to be fired at any time. Set FireDate to the date and time when you want to fire the notification.

Firing Notifications in a Particular Date and Time

You can set that a notification must be fired in a particular date and time. For example, to set a notification to be fired on the 16th of December of 2015 at 5:30 P.M., you could set FireDate like this:

Delphi:

MyNotification.FireDate := EncodeDateTime(2015, 12, 16, 17, 30, 00, 00);

C++:

MyNotification->FireDate = System::Dateutils::EncodeDateTime(2015, 12, 16, 17, 30, 00, 00);

When scheduling notifications to a particular date and time, you must bear in mind that if the FireDate you set has already passed, the notification is fired immediately.

Firing Notifications After a Period of Time

You can set that a notification must be fired after a period time. For example, to fire the notification in 1 minute and 30 seconds, you can do the following:

Delphi:

MyNotification.FireDate := Now + EncodeTime(0, 1, 30, 0);

C++:

MyNotification->FireDate = Now() + EncodeTime(0, 1, 30, 0);

If a notification is scheduled, and you create another notification with the same name (whether scheduled or not), any previous notification that was scheduled with that same name is overwritten.

Repeating Notifications

You can use RepeatInterval to schedule notifications to repeat after a period of time. You can use one of the interval types that TRepeatInterval defines: None, Second, Minute, Hour, Day, Week, Weekday, Month, Quarter, Year, or Era.

Warning: When you schedule a notification to repeat after a period of time using RepeatInterval, the notification continues repeating even after the application closes; ensure you deal properly with cancelling the notifications.

For example, to set a notification to repeat every hour, you could do the following:

Delphi:

MyNotification.RepeatInterval := TRepeatInterval.Hour;

C++:

MyNotification->RepeatInterval = TRepeatInterval::Hour;

Notification Sound

Enabling Notification Sounds

You can enable or disable the sound using EnableSound. By default EnableSound is set to True.

• In the case of OS X and iOS, even when the sound is enabled, if the application is in the foreground, the notification sound does not play; OS X and iOS plays the notification sound when the application is in the background or closed.
• In the case of Windows, the notification sound always plays; even if you disable the sound with EnableSound.

Customizing Notification Sounds

You can customize the sound of your notifications setting SoundName to the sound for your notification.

To add a custom notification sound follow these steps:

1. Drag and drop the sound file to the name of your project in the Project Manager, and confirm you want to add the file.
2. Go to Project > Deployment and set the correct remote paths of the file for the different platforms.
   • iOS:.\
3. Indicate the custom sound name, set SoundName according to the platform.

Delphi:

{$IFDEF IOS}
MyNotification.SoundName := 'nameOfSound.caf';
{$ENDIF}

C++:

#if defined(_PLAT_IOS)
myNotification->SoundName = "nameOfSound.caf";
#endif

Note: According to iOS documentation the sound file should have aiff, wav, or caf file extensions.

Ensure you add the appropriate unit to your project:

Delphi: Add System.IOUtils in the uses clause.

System.IOUtils;

C++: Add System.IOUtils.hpp in the header file .h of your project.

#include <System.IOUtils.hpp>

If the device is unable to find the custom sound that you set in your project, iOS plays the default sound, but the Android does not play any sound.

Notification Actions

Clicking the notifications in OS X, iOS, or Android, brings the application that sent the notification to the front, whether this application is running in the background or closed completely.

There is no particular behaviour when the user clicks the notification in Windows.

Adding Notification Actions

You can execute actions when the user clicks a notification. The event OnReceiveLocalNotification is fired when the user clicks a notification. Write an event handler to define an action.

The event handler for the OnReceiveLocalNotification even receives the TNotitication that the user clicked in the ANotification parameter; use the ANotification parameter to get further details about the notification the user clicked.

To show a message according to the notification the user clicked:

Delphi:

if ANotification.Name='ProcessCompleted' then
	ShowMessage('The process is completed.');

C++:

if (ANotification->Name == "ProcessCompleted") {
	ShowMessage("The process is completed.");
}

Notification Actions (OS X and iOS)

You can add an action button to an alert so the user can open the application clicking the button. For this feature to work, the user needs to set the style of notifications settings of the project to Alerts, for further information see how to set Notification Alerts in OS X and Notifications Alerts in iOS.

To add an action button, set the HasAction field to True. Use the AlertAction field to indicate the text of the button.

Delphi:

MyNotification.HasAction := True;
MyNotification.AlertAction := 'Open App';

C++:

MyNotification->HasAction = True;
MyNotification->AlertAction = "Open App";

Sending Notifications to the Notification Center

After you finish configuring all the settings for your notification, you must send your notification to the notification center to process it.

You can send notifications to the notification center using one of the following two methods.

• ScheduleNotification
• PresentNotification

ScheduleNotification

ScheduleNotification sends a scheduled notification to the notification center. If FireDate is Now, or if FireDate has a past TDateTime, then the notification is presented immediately; otherwise the notification is scheduled as indicated.

Warning: Windows does not support ScheduleNotification.

Delphi:

NotificationCenter1.ScheduleNotification(MyNotification);

C++:

NotificationCenter1->ScheduleNotification(MyNotification);

PresentNotification

PresentNotification presents the notification immediately regardless of the value of FireDate.

Delphi:

NotificationCenter1.PresentNotification(MyNotification);

C++:

NotificationCenter1->PresentNotification(MyNotification);

Cancelling Notifications

You can cancel notifications that are scheduled, notifications that repeat, and you can also remove notifications that are already displayed in the Action Center, Notification Center, or Notification Drawer.

CancelNotification

CancelNotification is used to cancel a scheduled notification or a notification that repeats. You need the Name of a notification to cancel it.

Delphi:

NotificationCenter1.CancelNotification('MyNotificationName');

C++:

NotificationCenter1->CancelNotification("MyNotificationName");

CancelAll

CancelAll cancels all notifications:

• The notifications that are scheduled will not be fired.
• The notifications that have repeat interval are cancelled.
• The notifications that are available in the Action Center, Notification Center, or Notification Drawer for this application are deleted.

Delphi:

NotificationCenter1.CancelAll;

C++:

NotificationCenter1->CancelAll();

Updating Notifications

You can update notifications that are pending to be fired using the Name, that is the unique identifier of the notification. To update a notification, follow these steps:

1. Create an instance of TNotification with the same Name as the one you want to update.
2. Configure the new instance with the settings that you want.
3. Send the notification to the notification center.

Updating future notifications, whether scheduled or with repeat interval, deletes the notifications that are already present Action Center, Notification Center, or Notification Drawer (if any), and overwrites any future notifications.

See Also

• Using the Mac OS X Notification Center
• Mobile Tutorial: Using Notifications (iOS and Android)
• Push Notifications
• System.Notification.TNotification
• System.Notification.TNotificationCenter

Code Samples

• FireMonkey Send Cancel Notification sample
• FireMonkey Android Notification Service sample
• FireMonkey Set Reset Badge Number sample
• OSX Dock Badges (Delphi)
• FireMonkey Notification Mac (Delphi)
• FireMonkey Notification Mac (C++)