MobileNotifications
From Xojo Documentation
| This class is supported on iOS. Use ＃If...＃Endif with the Target... constants to ensure you only use this class where it is supported. |
New in 2020r2
Manages all incoming and outgoing notifications.
| Enumerations | |||
|
| Shared Methods | ||||||||||||||
|
Notes
This class can't be instantiated. Instead add the NotificationCenter to your project (via the Insert menu) and then use that singleton to send and receive notifications. You should also always use the NotificationCenter singleton when calling any and all methods from MobileNotifications including the shared methods. Using the MobileNotifications class directly will result in events failing to be called.
There are two types of notifications: local and remote. Local notifications are those sent from your app to itself. For example, you might be scheduling a notification to remind the user to take some important action at a future date. Remote notifications are those received by your app from outside of itself.
Before you can send a notification or receive a remote one, you must get authorization to do so. How this is done depends on whether you are using local or remote notifications.
Getting Local Notification Authorization
Authorization for local notifications is done by calling the NotificationCenter.RequestAuthorization method. If it's successful, the AuthorizationSucceeded event will fire. This request needs to only be made once each time the app is launched therefore it should be done in the App.Opening event. When you request authorization, you also indicate the ways in which you wish the notification to be displayed. Having said that, your notification may end up not being displayed as you wished because of the user's notification preferences for your app, the device is in lower power mode, turned off, etc.
Sending Local Notifications
There are three types of notifications that can be sent from an app:
- Time Interval Notifications are delivered based on the number of seconds between the request and the delivery. Xojo allows you to use and Integer or a DateInterval to specify the interval. These use the TimeIntervalNotification class.
- Calendar Notifications are delivered based on a calendar date, specified with a DateTime. These use the CalendarNotification class.
- Location Notifications are delivered when the device moves into or out of a circular region defined by geographic coordinates and a radius. These use the LocationNotification class.
After creating a type of notification, send it with the NotificationCenter.Send method. If it was successfully sent, the NotificationCenter.NotificationSent event will be called.
When you send a notification, what you are really doing is scheduling it to be delivered by the OS itself. See the notification type classes above for example code.
Sending Remote Notifications
Apple's Push Notification Service uses different servers for testing versus shipping apps. Which one it uses is based upon whether or not you have turned on Build Settings > Build For App Store. See Apple's documentation for more details.
Receiving Notifications
When a notification arrives, how your app handles it depends on whether the app is in the foreground or not. If your app is in the foreground, the NotificationCenter.NotificationReceived event will be called and you can return a value that describes how you wish the notification to be presented to the user. If your app is in the background or not running at all, the OS will display the notification. When the user taps on it, only then will your app's NotificationCenter.UserResponded event will be called. You can also create your own custom user interfaces to provide more options when displaying notifications (called Response Categories) by calling the NotificationCenter.AddResponseCategory method.
Registering To Receive Remote Notifications
To be able to send remote notifications to your app, you will need to:
- Sign-in to your Apple Developer account and add remote notifications to your app's identifier.
- Sign up with a service that will act as an agent for sending remote notifications.
- Have your app register with Apple's Push Notification (APN) service to receive remote notifications. Each time your app launches, first check to see if the app is already registered to receive remote notifications by calling NotificationCenter.RegisteredForRemoteNotifications method from the App.Opening event. If this method returns False, call the NotificationCenter.RegisterForRemoteNotifications method. The NotificationCenter.RemoteRegistrationSucceeded event will be called if the registration is successful, returning a unique token. This token is required to be able to send remote notifications to this particular instance of the app. Store this token in your database where you keep user account information.
- Enable Remote Notifications for your project by clicking on iOS under Build Settings in the IDE navigator then clicking on the advanced tab in the Inspector then clicking the switch next to Remote Notifications.
 |
Do NOT store the token on the device as this is a security risk. |
Receiving Background Only Remote Notifications
Remote notifications provide the option to be sent as background only meaning that they will not present any user interface to the user. These are used when you need the app to take an action that does not require user interaction such as updating some local data. When a background only remote notification is received, the NotificationCenter.BackgroundNotificationReceived event is called.
Time Limit For Responding to Notifications
When you receive a notification while your app is in the background or not running at all, or a background only remote notification, the OS will give your app about 30 seconds to complete the event. If your app takes longer, the OS may terminate the app so whatever you do, do it quickly.
Testing Remote Notifications
Testing of remote notifications can be done locally via the simulator or on device or through Apple's Push Notification service as described earlier.
The iOS Simulator cannot receive remote notifications. However, you can simulate a remote notification for testing purposes by putting the text below into a file named with a .apns extension and dragging it into the simulator:
{ "Simulator Target Bundle": "your.bundle.identifier.here", "aps": { "alert": { "title" : "Chicken Avocado Taco Platter", "subtitle" : "All New Flavors!", "body" : "Special - Today Only $4.99" } } }
To test locally on a physical device, use this free utility.
Compatibility
iOS projects on iOS and iPadOS operating systems.
See Also
CalendarNotification, LocationNotification, Notification, NotificationContent, NotificationSettings, NotificationException, NotificationResponseCategory, NotificationSettings, RemoteNotification, and TimeIntervalNotification classes.