Behaviour

Sound

When a notification is about to be displayed on a device, the permissions requested from the user will be read by the device (see requestPermission). If sound permission has been granted, the device will alert the user to the notification audibly with sound. The sound used will be whatever the user has selected within the device settings.

You can however customise the sound played by providing a string value of an iOS resource, for example:

notifee.displayNotification({
  body: 'Custom sound',
  ios: {
    // iOS resource (.wav, aiff, .caf)
    sound: 'local.wav',
  },
});

To use the users default sound, set the value as default. For no sound, do not include the property.

If you are using a custom sound file, it must be less than 30 seconds in length, otherwise the system will play the default sound.

Interruption Levels

With iOS 15's Focus Mode, users are more in control of when app notifications can "interrupt" them with a sound or vibration. The interruptionLevel property controls the notification's importance and delivery timing. Accepted values: 'passive', 'active' (default), 'timeSensitive', 'critical'.

notifee.displayNotification({
  title: 'ALERT!',
  body: 'This is a critical notification!',
  ios: {
    interruptionLevel: 'timeSensitive',
  },
});

Foreground delivery events

On iOS, an EventType.DELIVERED event is emitted to onForegroundEvent when a Notify Kit-owned notification is presented to the user while the app is in the foreground (immediate displayNotification calls, trigger notifications that fire in foreground, and handleFcmMessage foreground displays). Use this for analytics, read-state tracking, or badge maintenance.

Trigger notifications that fire while the app is in background or killed do not emit DELIVERED on iOS — willPresentNotification: is only invoked in the foreground and the platform exposes no equivalent callback for background-presented local notifications. Android emits DELIVERED unconditionally in both cases. If you need delivery confirmation for background trigger notifications on iOS, query getDisplayedNotifications() after the app returns to foreground. See the events documentation for the full event shape.

Critical Notifications

In some scenarios you may wish to alert the user to a notification and bypass the users preferences such as the mute switch or Do Not Disturb mode.

To do this, request criticalAlert permission via requestPermission and set the critical flag on the notification:

// iOS > 12
notifee.requestPermission({
  //...,
  criticalAlert: true,
});

// iOS > 10
notifee.displayNotification({
  title: 'ALERT!',
  body: 'This is a critical notification!',
  ios: {
    critical: true,
    sound: 'local.wav',
  },
});

On iOS >= 12, you can further control the sound volume level of a critical notification by passing a criticalVolume property to your ios notification options:

// iOS > 10
notifee.displayNotification({
  title: 'ALERT!',
  body: 'This is a critical notification!',
  ios: {
    critical: true,
    sound: 'local.wav',
    // iOS > 12
    // play at 90% sound volume
    criticalVolume: 0.9,
  },
});

The criticalVolume value accepts a float value between 0.0 & 1.0, with 1.0 representing full volume.

Critical notifications require a special entitlement issued by Apple. A request can be submitted at https://developer.apple.com/contact/request/notifications-critical-alerts-entitlement.