Permissions

Before diving into requesting notification permissions from your users, it is important to understand how Apple and web platforms handle permissions.

Notifications cannot be shown to users if the user has not "granted" your application permission. The overall notification permission of a single application can be either be "not determined", "granted" or "declined". Upon installing a new application, the default status is "not determined".

In order to receive a "granted" status, you must request permission from your user (see below). The user can either accept or decline your request to grant permissions. If granted, notifications will be displayed based on the permission settings which were requested.

If the user declines the request, you cannot re-request permission, trying to request permission again will immediately return a "denied" status without any user interaction - instead the user must manually enable notification permissions from the device Settings UI (or via a custom UI).

Requesting permissions

As explained in the Usage documentation, permission must be requested from your users in order to display remote notifications from FCM, via the requestPermission API:

FirebaseMessaging messaging = FirebaseMessaging.instance;
NotificationSettings settings = await messaging.requestPermission(
alert: true,
announcement: false,
badge: true,
carPlay: false,
criticalAlert: false,
provisional: false,
sound: true,
);
if (settings.authorizationStatus == AuthorizationStatus.authorized) {
print('User granted permission');
} else if (settings.authorizationStatus == AuthorizationStatus.provisional) {
print('User granted provisional permission');
} else {
print('User declined or has not accepted permission');
}

On Apple based platforms, once a permission request has been handled by the user (authorized or denied), it is not possible to re-request permission. The user must instead update permission via the device Settings UI:

  • If the user denied permission altogether, they must enable app permission fully.
  • If the user accepted requested permission (without sound), they must specifically enable the sound option themselves.

Permission settings

Although overall notification permission can be granted, the permissions can be further broken down into 'settings'.

Settings are used by the device to control notifications behavior, for example alerting the user with sound. When requesting permission, you can provide arguments if you wish to override the defaults. This is demonstrated in the above example.

The full list of permission settings can be seen in the table below along with their default values:

PermissionDefaultDescription
alerttrueSets whether notifications can be displayed to the user on the device.
announcementfalseIf enabled, Siri will read the notification content out when devices are connected to AirPods.
badgetrueSets whether a notification dot will appear next to the app icon on the device when there are unread notifications.
carPlaytrueSets whether notifications will appear when the device is connected to CarPlay.
provisionalfalseSets whether provisional permissions are granted. See Provisional permission for more information.
soundtrueSets whether a sound will be played when a notification is displayed on the device.

The settings provided will be stored by the device and will be visible in the iOS Settings UI for your application.

You can also read the current permissions without attempting to request them via the getNotificationSettings method:

NotificationSettings settings = await messaging.getNotificationSettings();

Provisional authorization

Devices on iOS 12+ can use provisional authorization. This type of permission system allows for notification permission to be instantly granted without displaying a dialog to your user. The permission allows notifications to be displayed quietly (only visible within the device notification center).

To enable provision permission, set the provisional argument to true when requesting permission:

NotificationSettings settings = await messaging.requestPermission(
provisional: true,
);

When a notification is displayed on the device, the user will be presented with several actions prompting to keep receiving notifications quietly, enable full notification permission or turn them off:

iOS Provisional Notification Example