Behaviour

Control how notifications behave when they are displayed to your users.

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 new Focus Mode, users are more in control over when app notifications can “interrupt” them with a sound or vibration. We can make use of the new interruptionLevel API to control the notification’s importance and required delivery timing.

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

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.


Copyright 2020 - 2021 © Invertase Limited

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License and code samples are licensed under the Apache 2.0 License.

All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.