Expo Notifications

https://docs.expo.dev/versions/latest/sdk/notifications
Admin
A library that provides an API to fetch push notification tokens and to present, schedule, receive...
Tokens:11,916
Snippets:79
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### requestPermissionsAsync(permissions)

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Prompts the user for notification permissions based on the optional request configuration. Defaults to asking to display alerts, set badge counts, and play sounds.

```APIDOC
### `requestPermissionsAsync(permissions)`

**Supported Platforms:** Android, iOS

#### Description
Prompts the user for notification permissions according to the request. Request defaults to asking the user to allow displaying alerts, setting badge count, and playing sounds.

#### Parameters
- `permissions` (NotificationPermissionsRequest, optional) - An object representing configuration for the request scope.

#### Returns
`Promise<NotificationPermissionsStatus>` - Resolves to an object representing permission settings.

#### Example
```ts
import * as Notifications from 'expo-notifications';

export function requestPermissionsAsync() {
  return Notifications.requestPermissionsAsync({
    ios: {
      allowAlert: true,
      allowBadge: true,
      allowSound: true,
    },
  });
}
```
```

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

### PushTokenListener(token)

Source: https://docs.expo.dev/versions/latest/sdk/notifications

A callback function listener accepting a device push token as an argument. Do not invoke getDevicePushTokenAsync inside this listener to prevent infinite loops.

```APIDOC
### `PushTokenListener(token)`

**Supported Platforms:** Android, iOS

A function accepting a device push token (`DevicePushToken`) as an argument.

> **Note:** You should not call `getDevicePushTokenAsync` inside this function, as it triggers the listener and may lead to an infinite loop.

#### Parameters
- **token** (`DevicePushToken`) - The device push token object received from the platform.

#### Returns
- `void`
```

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

### Configure foreground notification behavior with setNotificationHandler

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Sets a handler callback to decide whether an incoming notification received while the app is running should be presented. The handler must return a behavior object within 3 seconds, otherwise the notification is discarded.

```jsx
import * as Notifications from 'expo-notifications';

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});
```

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

### Configure push notification deep linking with React Navigation in App.tsx

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Set up React Navigation's linking configuration to handle redirects from push notifications in `NavigationContainer`. Implements `getInitialURL` to check for initial notification payloads and `subscribe` to listen for incoming notification responses alongside standard deep links.

```tsx
import React from 'react';
import { Linking } from 'react-native';
import * as Notifications from 'expo-notifications';
import { NavigationContainer } from '@react-navigation/native';

export default function App() {
  return (
    <NavigationContainer
      linking={{
        config: {
          // Configuration for linking
        },
        async getInitialURL() {
          // First, you may want to do the default deep link handling
          // Check if app was opened from a deep link
          const url = await Linking.getInitialURL();

          if (url != null) {
            return url;
          }

          // Handle URL from expo push notifications
          const response = Notifications.getLastNotificationResponse();
          const notificationUrl = response?.notification.request.content.data?.url;
          if (typeof notificationUrl === 'string') {
            return notificationUrl;
          }
        },
        subscribe(listener) {
          const onReceiveURL = ({ url }: { url: string }) => listener(url);

          // Listen to incoming links from deep linking
          const eventListenerSubscription = Linking.addEventListener('url', onReceiveURL);

          // Listen to expo push notifications
          const subscription = Notifications.addNotificationResponseReceivedListener(response => {
            const url = response.notification.request.content.data?.url;

            // Any custom logic to see whether the URL needs to be handled
            //...

            if (typeof url === 'string') {
              // Let React Navigation handle the URL
              listener(url);
            }
          });

          return () => {
            // Clean up the event listeners
            eventListenerSubscription.remove();
            subscription.remove();
          };
        },
      }}>
      {/* Your app content */}
    </NavigationContainer>
  );
}
```

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

### Handle push notification deep links with Expo Router in app/_layout.tsx

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Configure the root layout to listen for incoming and initial notification events using Expo Router's built-in deep linking. Checks `getLastNotificationResponse()` on mount and adds a listener with `addNotificationResponseReceivedListener` to navigate via `router.push()`.

```tsx
import { useEffect } from 'react';
import * as Notifications from 'expo-notifications';
import { Slot, router } from 'expo-router';

function useNotificationObserver() {
  useEffect(() => {
    function redirect(notification: Notifications.Notification) {
      const url = notification.request.content.data?.url;
      if (typeof url === 'string') {
        router.push(url);
      }
    }

    const response = Notifications.getLastNotificationResponse();
    if (response?.notification) {
      redirect(response.notification);
    }

    const subscription = Notifications.addNotificationResponseReceivedListener(response => {
      redirect(response.notification);
    });

    return () => {
      subscription.remove();
    };
  }, []);
}

export default function Layout() {
  useNotificationObserver();

  return <Slot />;
}
```

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

### Request notification permissions with requestPermissionsAsync

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Prompts the user for notification permissions according to the specified configuration scope for alerts, badges, and sounds on iOS and Android. Request defaults to asking to allow displaying alerts, setting badge counts, and playing sounds.

```ts
import * as Notifications from 'expo-notifications';

export function requestPermissionsAsync() {
  return Notifications.requestPermissionsAsync({
    ios: {
      allowAlert: true,
      allowBadge: true,
      allowSound: true,
    },
  });
}
```

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

### Configure expo-notifications plugin in app.json

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Configures the expo-notifications config plugin in app.json with notification icons, tint color, default channels, sound assets, and background notification settings. Changes require generating a new native app binary to take effect.

```json
{
  "expo": {
    "plugins": [
      [
        "expo-notifications",
        {
          "icon": "./local/assets/notification_icon.png",
          "color": "#ffffff",
          "defaultChannel": "default",
          "sounds": [
            "./local/assets/notification_sound.wav",
            "./local/assets/notification_sound_other.wav"
          ],
          "enableBackgroundRemoteNotifications": false
        }
      ]
    ]
  }
}
```

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

### setNotificationHandler(handler)

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Sets a callback that determines whether a notification received while the app is running should be displayed to the user. The handler must respond within 3 seconds, or the notification will be discarded by default.

```APIDOC
### `setNotificationHandler(handler)`

**Supported platforms**: Android, iOS

Sets a callback that decides whether an incoming notification should be shown to the user when the app is running in the foreground.

#### Parameters

- `handler` (`NotificationHandler | null`) - Either `null` (to clear the handler) or a `NotificationHandler` object.

#### Returns

`void`

#### Example

```jsx
import * as Notifications from 'expo-notifications';

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});
```
```

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

### setNotificationCategoryAsync(identifier, actions, options)

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Sets and registers a new interactive notification category with actions and configuration options. Returns a Promise resolving to the created category.

```APIDOC
### setNotificationCategoryAsync(identifier, actions, options)

Sets the new notification category.

#### Supported Platforms
- Android
- iOS

#### Parameters
- **identifier** (`string`) - A string to associate as the ID of this category. You will pass this string in as the `categoryIdentifier` in your `NotificationContent` to associate a notification with this category. Avoid using `:` or `-` characters.
- **actions** (`NotificationAction[]`) - An array of `NotificationAction`, which describe the actions associated with this category.
- **options** (`NotificationCategoryOptions`, optional) - An optional object of additional configuration options for your category.

#### Returns
`Promise<NotificationCategory>` - A Promise which resolves to the category you just have created.
```

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

### getPermissionsAsync()

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Checks the current permission settings related to notifications without triggering a user prompt. Supported on Android and iOS platforms.

```APIDOC
### `getPermissionsAsync()`

**Supported Platforms:** Android, iOS

#### Description
Calling this function checks current permissions settings related to notifications. It lets you verify whether the app is currently allowed to display alerts, play sounds, etc. There is no user-facing effect of calling this.

#### Returns
`Promise<NotificationPermissionsStatus>` - Resolves to an object representing permission settings.

#### Example
```ts
import * as Notifications from 'expo-notifications';

export async function allowsNotificationsAsync() {
  const settings = await Notifications.getPermissionsAsync();
  return (
    settings.granted || settings.ios?.status === Notifications.IosAuthorizationStatus.PROVISIONAL
  );
}
```
```

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

### getNotificationCategoriesAsync()

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Fetches information about all known notification categories. Returns a Promise resolving to an array of NotificationCategory objects.

```APIDOC
### getNotificationCategoriesAsync()

Fetches information about all known notification categories.

#### Supported Platforms
- Android
- iOS

#### Parameters
None.

#### Returns
`Promise<NotificationCategory[]>` - A Promise which resolves to an array of `NotificationCategory` objects. On platforms that do not support notification channels, it will always resolve to an empty array.
```

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

### Check notification permissions with getPermissionsAsync

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Checks current notification permission settings to verify if the app can display alerts, play sounds, or has provisional authorization on iOS. Calling this function has no user-facing effect.

```ts
import * as Notifications from 'expo-notifications';

export async function allowsNotificationsAsync() {
  const settings = await Notifications.getPermissionsAsync();
  return (
    settings.granted || settings.ios?.status === Notifications.IosAuthorizationStatus.PROVISIONAL
  );
}
```

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

### deleteNotificationCategoryAsync(identifier)

Source: https://docs.expo.dev/versions/latest/sdk/notifications

Deletes the interactive notification category associated with the provided identifier. Returns a Promise resolving to true if deleted or false otherwise.

```APIDOC
### deleteNotificationCategoryAsync(identifier)

Deletes the category associated with the provided identifier.

#### Supported Platforms
- Android
- iOS

#### Parameters
- **identifier** (`string`) - Identifier initially provided to `setNotificationCategoryAsync` when creating the category.

#### Returns
`Promise<boolean>` - A Promise which resolves to `true` if the category was successfully deleted, or `false` if it was not (for example, if trying to delete a non-existent category).
```
Tokens:
Raw