Class

# MobileNotifications

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Manages all incoming and outgoing notifications.

<div class="note">

<div class="title">

Note

</div>

You cannot instantiate this class. The `NotificationCenter</api/mobile/notificationcenter>` is a singleton instance of this class.

</div>

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                                                     | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                      | Returns                                     | Shared |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|--------|
| `AddResponseCategory<mobilenotifications.addresponsecategory>`                           | category As `NotificationResponseCategory</api/user_interface/notifications/notificationresponsecategory>`                                                                                                                                                                                                                                                                                                                      |                                             | ✓      |
| `Handle<mobilenotifications.handle>`                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Ptr</api/data_types/additional_types/ptr>` | ✓      |
| `RegisteredForRemoteNotifications<mobilenotifications.registeredforremotenotifications>` |                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Boolean</api/data_types/boolean>`          | ✓      |
| `RegisterForRemoteNotifications<mobilenotifications.registerforremotenotifications>`     |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `RemoveAllDeliveredNotifications<mobilenotifications.removealldeliverednotifications>`   |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `RemoveAllPendingNotifications<mobilenotifications.removeallpendingnotifications>`       |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `RemoveAllResponseCategories<mobilenotifications.removeallresponsecategories>`           |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `RemoveDeliveredNotifications<mobilenotifications.removedeliverednotifications>`         | identifiers() As `String</api/data_types/string>`                                                                                                                                                                                                                                                                                                                                                                               |                                             | ✓      |
| `RemovePendingRequests<mobilenotifications.removependingrequests>`                       | identifiers() As `String</api/data_types/string>`                                                                                                                                                                                                                                                                                                                                                                               |                                             | ✓      |
| `RequestAuthorization<mobilenotifications.requestauthorization>`                         | `ParamArray</api/language/paramarray>` options() As MobileNotifications                                                                                                                                                                                                                                                                                                                                                         |                                             | ✓      |
| `RequestDeliveredNotifications<mobilenotifications.requestdeliverednotifications>`       |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `RequestPendingNotifications<mobilenotifications.requestpendingnotifications>`           |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |
| `Send<mobilenotifications.send>`                                                         | Latitude As `Double</api/data_types/double>`, Longitude As `Double</api/data_types/double>`, Radius As `Double</api/data_types/double>`, identifier As `String</api/data_types/string>`, mode As `LocationNotification<locationnotification.modes>`, content As `NotificationContent</api/user_interface/notifications/notificationcontent>`, shouldRepeat As `Boolean</api/data_types/boolean>` = `False</api/language/false>` |                                             | ✓      |
| `UnregisterForRemoteNotifications<mobilenotifications.unregisterforremotenotifications>` |                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             | ✓      |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                                                 | Parameters                                                                                                                                                                   | Returns                                                    |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| `AuthorizationSucceeded<mobilenotifications.authorizationsucceeded>`                 | settings As `NotificationSettings</api/user_interface/notifications/notificationsettings>`                                                                                   |                                                            |
| `BackgroundNotificationReceived<mobilenotifications.backgroundnotificationreceived>` | userInfo As `Dictionary</api/language/dictionary>`                                                                                                                           |                                                            |
| `DeliveredNotifications<mobilenotifications.deliverednotifications>`                 | notifications() As `Notification</api/user_interface/notifications/notification>`                                                                                            |                                                            |
| `Error<mobilenotifications.error>`                                                   | error As `NotificationException</api/exceptions/notificationexception>`, notification As `Notification</api/user_interface/notifications/notification>`                      |                                                            |
| `NotificationReceived<mobilenotifications.notificationreceived>`                     | notification As `Notification</api/user_interface/notifications/notification>`                                                                                               | `PresentationModes<mobilenotifications.presentationmodes>` |
| `NotificationSent<mobilenotifications.notificationsent>`                             | notification As `Notification</api/user_interface/notifications/notification>`                                                                                               |                                                            |
| `OpenNotificationsSettings<mobilenotifications.opennotificationssettings>`           |                                                                                                                                                                              |                                                            |
| `PendingNotifications<mobilenotifications.pendingnotifications>`                     | notifications() As `Notification</api/user_interface/notifications/notification>`                                                                                            |                                                            |
| `RemoteRegistrationSucceeded<mobilenotifications.remoteregistrationsucceeded>`       | token As `String</api/data_types/string>`                                                                                                                                    |                                                            |
| `UserResponded<mobilenotifications.userresponded>`                                   | notification As `Notification</api/user_interface/notifications/notification>`, action As `String</api/data_types/string>`, textResponse As `String</api/data_types/string>` |                                                            |

## Enumerations

<div id="mobilenotifications.authorizationoptions">

<div class="rst-class">

forsearch

</div>

</div>

MobileNotifications.AuthorizationOptions

### AuthorizationOptions

> The available ways in which your app can request notifications to be displayed when received by the target app.
>
> | Enum                         | Description                                                                                                                                                               |
> |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> | Alert                        | Shows an alert when a notification is received.                                                                                                                           |
> | Announcement                 | Allows announcements to be read over AirPods.                                                                                                                             |
> | Badge                        | Displays a badge on the application icon when a notification is received.                                                                                                 |
> | CarPlay                      | Allows received notifications to be displayed in CarPlay.                                                                                                                 |
> | CriticalAlert                | Ability to show notifications that override sound and banner restrictions. This option is designed for government agencies and requires a special entitlement from Apple. |
> | None                         | Don't display the notification.                                                                                                                                           |
> | ProvidesNotificationSettings | Indicates to the iOS that your app provides its own notification settings `screen</api/user_interface/mobile/mobilescreen>`.                                              |
> | Provisional                  | Ability to show notifications on a provisional basis which the user can decide to accept later.                                                                           |
> | Sound                        | Ability to play a sound when a notification is delivered.                                                                                                                 |

<div id="mobilenotifications.presentationmodes">

<div class="rst-class">

forsearch

</div>

</div>

MobileNotifications.PresentationModes

### PresentationModes

> The ways in which you can request the notification received to be displayed to the user.
>
> | Enum          |
> |---------------|
> | Alert         |
> | AlertAndBadge |
> | AlertAndSound |
> | All           |
> | Badge         |
> | None          |
> | Sound         |
> | SoundAndBadge |

<div id="mobilenotifications.remotefetchresults">

<div class="rst-class">

forsearch

</div>

</div>

MobileNotifications.RemoteFetchResults

### RemoteFetchResults

> The possible responses when receiving a remote notification in the background.
>
> | Enum    | Description                                                                                              |
> |---------|----------------------------------------------------------------------------------------------------------|
> | NewData | The background update succeeded and there was new data for the app.                                      |
> | NoData  | The background update succeeded, but there was no new data for the app.                                  |
> | Failed  | The background update failed, as in, your app tried to retrieve updated data and the URL request failed. |

## Method descriptions

<div id="mobilenotifications.addresponsecategory">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.AddResponseCategory

**AddResponseCategory**(category As `NotificationResponseCategory</api/user_interface/notifications/notificationresponsecategory>`)

> Adds a set of buttons and/or text entry fields so incoming notifications can be interactive.
>
> This method is `shared</api/language/shared>`.
>
> Add a response category that will display a dialog with a message and two buttons when the LargePizzaSale notification is received:
>
> ``` xojo
> Var responseCategory As New NotificationResponseCategory("LargePizzaSale")
> responseCategory.Caption = "Large pizzas are on sale tonight only!"
> responseCategory.Actions.Add(New NotificationResponseButton("Order!", "yes")
> responseCategory.Actions.Add(New NotificationResponseButton("No Thanks", "no")
> NotificationCenter.AddResponseCategory(responseCategory)
> ```

<div id="mobilenotifications.handle">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.Handle

**Handle** As `Ptr</api/data_types/additional_types/ptr>`

> A pointer to the underlying User Notifications Center `declares</api/language/declare>`.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.registeredforremotenotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RegisteredForRemoteNotifications

**RegisteredForRemoteNotifications** As `Boolean</api/data_types/boolean>`

> Returns `True</api/language/true>` if the app is already registered for remote notifications.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.registerforremotenotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RegisterForRemoteNotifications

**RegisterForRemoteNotifications**

> Asks the device to register the app for receiving Remote Notifications and requests a token from Apple.
>
> This method is `shared</api/language/shared>`.
>
> If the registration succeeds, the `RemoteRegistrationSucceeded<mobilenotifications.remoteregistrationsucceeded>` event will be called.

<div id="mobilenotifications.removealldeliverednotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemoveAllDeliveredNotifications

**RemoveAllDeliveredNotifications**

> Removes all notifications that have already been delivered.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.removeallpendingnotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemoveAllPendingNotifications

**RemoveAllPendingNotifications**

> Removes all pending notifications in the queue.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.removeallresponsecategories">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemoveAllResponseCategories

**RemoveAllResponseCategories**

> Removes all response categories.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.removedeliverednotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemoveDeliveredNotifications

**RemoveDeliveredNotifications**(identifiers() As `String</api/data_types/string>`)

> Removes the specified notifications that have already been delivered.
>
> This method is `shared</api/language/shared>`.
>
> You may wish to remove delivered notifications if no longer wish the user to see the notification in the iOS Notification Center.

<div id="mobilenotifications.removependingrequests">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemovePendingRequests

**RemovePendingRequests**(identifiers() As `String</api/data_types/string>`)

> Removes the specified pending local notifications from the queue.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.requestauthorization">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RequestAuthorization

**RequestAuthorization**(`ParamArray</api/language/paramarray>` options() As MobileNotifications)

> Requests from the OS permission to send local notifications.
>
> This method is `shared</api/language/shared>`.
>
> If the `options<mobilenotifications.authorizationoptions>` you request will be visible the other (an alert, badge, sound, etc.) and the app hasn't made this request before, the OS will display a dialog asking the user to give permission. Otherwise, your request will succeed assuming the user has not otherwise disallowed the `options<mobilenotifications.authorizationoptions>` you requested.
>
> Because the user can change their notification settings for your app at any time, you should call RequestAuthorization in the `Opening<mobileapplication.opening>` event each time your app launches.
>
> The `AuthorizationSucceeded<mobilenotifications.authorizationsucceeded>` event will be called if the request is successful.
>
> Requesting authorization to display a notification via a badge and sound in the app's `Opening<mobileapplication.opening>` event:
>
> ``` xojo
> NotificationCenter.RequestAuthorization(MobileNotifications.AuthorizationOptions.Badge, MobileNotifications.AuthorizationOptions.Sound)
> ```

<div id="mobilenotifications.requestdeliverednotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RequestDeliveredNotifications

**RequestDeliveredNotifications**

> Requests that the OS send the app an array of notifications that it has received for the app since the last time the app was launched. The array is delivered via the `DeliveredNotifications<mobilenotifications.deliverednotifications>` event.
>
> This method is `shared</api/language/shared>`.

<div id="mobilenotifications.requestpendingnotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RequestPendingNotifications

**RequestPendingNotifications**

> Requests that the OS send the app an array of notifications set for a future date/time that it has received for the app since the last time the app was launched.
>
> This method is `shared</api/language/shared>`.
>
> The array is delivered via the `PendingNotifications<mobilenotifications.pendingnotifications>` event.

<div id="mobilenotifications.send">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.Send

**Send**(Latitude As `Double</api/data_types/double>`, Longitude As `Double</api/data_types/double>`, Radius As `Double</api/data_types/double>`, identifier As `String</api/data_types/string>`, mode As `LocationNotification<locationnotification.modes>`, content As `NotificationContent</api/user_interface/notifications/notificationcontent>`, shouldRepeat As `Boolean</api/data_types/boolean>` = `False</api/language/false>`)

> Sends the notification to the OS for delivery when the device enters or exists a region as specified by *radius* meters around a specific *latitude* and *longitude*.
>
> This method is `shared</api/language/shared>`.
>
> Send a notification right now:
>
> ``` xojo
> NotificationCenter.Send(New NotificationContent("The connection has been lost."))
> ```
>
> Send a notification every hour:
>
> ``` xojo
> Var id As String
> Var interval As New DateInterval(0, 0, 0, 1)
> id = NotificationCenter.Send(interval, New NotificationContent("Are we there yet?"), True)
> ```
>
> Send a notification in 30 seconds:
>
> ``` xojo
> Var id As String
> id = NotificationCenter.Send(30, New NotificationContent("Your access code has expired."))
> ```
>
> Send a notification on a specific date every year:
>
> ``` xojo
> Var id As String
> Var birthday As DateTime(2890, 9, 22)
> id = NotificationCenter.Send(birthday, New NotificationContent("Happy Birthday, Bilbo!"), True)
> ```
>
> Send a notification to remind the user to visit the President of the United States when they are in town:
>
> ``` xojo
> Var id As String
> id = NotificationCenter.Send(38.897957, -77.036560, 1000, New NotificationContent("Visit the POTUS."), True)
> ```

<div id="mobilenotifications.unregisterforremotenotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.UnregisterForRemoteNotifications

**UnregisterForRemoteNotifications**

> Disconnects the device from Apple's Push Notification service such that sending a remote notification to the previously retrieved token will fail.
>
> This method is `shared</api/language/shared>`.

## Event descriptions

<div id="mobilenotifications.authorizationsucceeded">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.AuthorizationSucceeded

**AuthorizationSucceeded**(settings As `NotificationSettings</api/user_interface/notifications/notificationsettings>`)

> Your app's request to send local notifications was granted.

<div id="mobilenotifications.backgroundnotificationreceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.BackgroundNotificationReceived

**BackgroundNotificationReceived**(userInfo As `Dictionary</api/language/dictionary>`)

> A remote notification has been received indicating that the app should retrieve some data in the background.
>
> According to Apple, your app is given approximately 30 seconds to download the new data. The `return value<mobilenotifications.remotefetchresults>` is a hint to iOS so it knows whether or not to repeat the request.

<div id="mobilenotifications.deliverednotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.DeliveredNotifications

**DeliveredNotifications**(notifications() As `Notification</api/user_interface/notifications/notification>`)

> Delivers an array of notifications for the app that have been received by the OS since the last the app was launched.
>
> This event is called in response to a call to RequestDeliveredNotifications.

<div id="mobilenotifications.error">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.Error

**Error**(error As `NotificationException</api/exceptions/notificationexception>`, notification As `Notification</api/user_interface/notifications/notification>`)

> Occurs when the `Notification</api/user_interface/notifications/notification>` could not be sent.
>
> There are three reasons why an error occurs:
>
> - There is an error sending a particular `Notification</api/user_interface/notifications/notification>`, in which case `Notification</api/user_interface/notifications/notification>` will contain the `Notification</api/user_interface/notifications/notification>` object.
> - The user has declined to allow local notifications. in which case, the `Notification</api/user_interface/notifications/notification>` will be `Nil</api/language/nil>`.
> - The user has declined to allow or the device is not capable of receiving remote notifications in which case, `Notification</api/user_interface/notifications/notification>` will be `Nil</api/language/nil>`.

<div id="mobilenotifications.notificationreceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.NotificationReceived

**NotificationReceived**(notification As `Notification</api/user_interface/notifications/notification>`) As `PresentationModes<mobilenotifications.presentationmodes>`

> A local `Notification</api/user_interface/notifications/notification>` has been received while your app was in the foreground.
>
> Return the way in which the notification should be presented via a `PresentationModes<mobilenotifications.presentationmodes>` value.

<div id="mobilenotifications.notificationsent">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.NotificationSent

**NotificationSent**(notification As `Notification</api/user_interface/notifications/notification>`)

> The local `Notification</api/user_interface/notifications/notification>` was successful scheduled.
>
> This event is called after the `Send<mobilenotifications.send>` method is used to schedule a notification.

<div id="mobilenotifications.opennotificationssettings">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.OpenNotificationsSettings

**OpenNotificationsSettings**

> The user has tapped on the link on the notifications settings panel in the Settings app.
>
> If, when `requesting authorization<mobilenotifications.requestauthorization>` to send notifications, you included the `ProvidesNotificationSettings<mobilenotifications.authorizationoptions>` option, a link to your app will be included in the app's notification settings in the Notifications section of the Settings app. Should the user tap on that link, this event will fire. Your app should display it's own custom notification settings `dialog</api/user_interface/mobile/mobilescreen>`.

<div id="mobilenotifications.pendingnotifications">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.PendingNotifications

**PendingNotifications**(notifications() As `Notification</api/user_interface/notifications/notification>`)

> Delivers an array of notifications for the app that are set for a future date/time and have been received by the OS since the last the app was launched.
>
> This event is called in response to a call to RequestPendingNotifications.

<div id="mobilenotifications.remoteregistrationsucceeded">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.RemoteRegistrationSucceeded

**RemoteRegistrationSucceeded**(token As `String</api/data_types/string>`)

> The request to send remote notifications succeeded.
>
> This event is called in response to calling the `RegisterForRemoteNotifications<mobilenotifications.registerforremotenotifications>` method.
>
> The device token passed was created by and registered with Apple's Push Notification service (APNs). The token is unique to this instance of your app. If the user reinstalls the app for any reason, calling `RegisterForRemoteNotifications<mobilenotifications.registerforremotenotifications>` will generate a new token.
>
> This token is required in order to send remote notifications to the instance of the app the token represents. Therefore you will want to store the token in the database where you keep information about the user.
>
> <div class="warning">
>
> <div class="title">
>
> Warning
>
> </div>
>
> Do not store the token on the device as this presents a security risk.
>
> </div>

<div id="mobilenotifications.userresponded">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

MobileNotifications.UserResponded

**UserResponded**(notification As `Notification</api/user_interface/notifications/notification>`, action As `String</api/data_types/string>`, textResponse As `String</api/data_types/string>`)

> A local notification was received while your app was in the background and the user responded to the notification by tapping on it.
>
> By default this event will occur if the user touches the notification to bring your app to the foreground. You may add other actions by adding a `NotificationResponseCategory</api/user_interface/notifications/notificationresponsecategory>`.

## 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 <span class="title-ref">MobileNotifications</span> including the shared methods. Using the <span class="title-ref">MobileNotifications</span> 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<mobilenotifications.requestauthorization>` method. If it's successful, the `AuthorizationSucceeded<mobilenotifications.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<mobileapplication.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</api/data_types/integer>` or a `DateInterval</api/os/dateinterval>` to specify the interval. These use the `TimeIntervalNotification</api/user_interface/notifications/timeintervalnotification>` class.
- Calendar Notifications are delivered based on a calendar date, specified with a `DateTime</api/data_types/datetime>`. These use the `CalendarNotification</api/user_interface/notifications/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</api/user_interface/notifications/locationnotification>` class.

After creating a type of notification, send it with the `NotificationCenter.Send<mobilenotifications.send>` method. If it was successfully sent, the `NotificationCenter.NotificationSent<mobilenotifications.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](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc) 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<mobilenotifications.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<mobilenotifications.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<mobilenotifications.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](https://developer.apple.com) 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<mobilenotifications.registeredforremotenotifications>` method from the `App.Opening<mobileapplication.opening>` event. If this method returns `False</api/language/false>`, call the `NotificationCenter.RegisterForRemoteNotifications<mobilenotifications.registerforremotenotifications>` method. The `NotificationCenter.RemoteRegistrationSucceeded<mobilenotifications.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 the `enable the Remote Notifications entitlement</topics/application_structure/ios/ios_apps/entitlements_and_additional_information>` for your project.

<div class="warning">

<div class="title">

Warning

</div>

Do NOT store the token on the device as this is a security risk.

</div>

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### 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<mobilenotifications.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:

``` json
{
    "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](https://github.com/onmyway133/PushNotifications/releases).

## Compatibility

|                       |        |
|-----------------------|--------|
| **Project Types**     | Mobile |
| **Operating Systems** | iOS    |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `CalendarNotification</api/user_interface/notifications/calendarnotification>`, `LocationNotification</api/user_interface/notifications/locationnotification>`, `Notification</api/user_interface/notifications/notification>`, `NotificationContent</api/user_interface/notifications/notificationcontent>`, `NotificationSettings</api/user_interface/notifications/notificationsettings>`, `NotificationException</api/exceptions/notificationexception>`, `NotificationResponseCategory</api/user_interface/notifications/notificationresponsecategory>`, `NotificationSettings</api/user_interface/notifications/notificationsettings>`, `RemoteNotification</api/user_interface/notifications/remotenotification>`, and `TimeIntervalNotification</api/user_interface/notifications/timeintervalnotification>` classes.

</div>