Expo Push Notifications from Setup to Delivery with expo-notifications

📅

loading..🐩🐩🐩🐩

Before We Begin 🔗

Push notifications let mobile apps deliver important information and encourage users to return, even when they aren't using the app. Setting them up for the first time can feel complicated.

We'll walk through push notifications in an Expo React Native app, from installing the tools and requesting permission to getting a unique token, sending a notification from a server, and handling it in the app.

Why Use Push Notifications, and How Do They Work? 🔗

Notifications can bring users back to your app and deliver information promptly, including new messages, event reminders, and promotions. Here's the overall flow in Expo.

App
— Your Expo app runs on the user's device.
Get a push token
— The app asks for notification permission. Once the user grants it, the app obtains a unique
Expo push token
that identifies the device.
Store the token
— The app sends the token to your backend. Record which user it belongs to so you can send notifications to that user later.
Request delivery
— To notify one or more users, your server sends their stored tokens and the message to the
Expo Push Service
API.
Expo Push Service
— Expo receives your request and handles delivery.
Native push services (APNs/FCM)
— Expo forwards the message to APNs for iOS or FCM for Android.
Device delivery
— APNs or FCM delivers the notification to the device.
App handling
— The app can process the notification, display it, or take a specific action.

Expo provides the expo-notifications library to help implement this flow. Let's use it to build the feature.

Step 1: Install expo-notifications 🔗

First, install expo-notifications. In an Expo project, use expo install in place of npm or yarn to install compatible native modules.

npx expo install expo-notifications expo-device expo-constants

The expo-notifications library requests permission and obtains the ExpoPushToken used for delivery.

The expo-device package checks whether the app is running on a physical device.

The expo-constants package retrieves projectId from the app configuration.

Step 2: Ask for Notification Permission 🔗

We'll start writing code here. You can find the complete example at the end.

🖐️

Test on a physical device. The Android and iOS simulators do not work for this example.

You need explicit permission from the user to send notifications. This is an operating system requirement on iOS and Android and helps protect user privacy.

Check and Request Permission 🔗

At startup or before a feature needs notifications, check the current permission status. If permission has not been granted, request it using the expo-notifications functions.

import * as Device from 'expo-device';
import * as Notifications from 'expo-notifications';
import Constants from 'expo-constants';
 
function handleRegistrationError(errorMessage: string) {
  alert(errorMessage);
  throw new Error(errorMessage);
}
 
async function registerForPushNotificationsAsync() {
  if (Platform.OS === 'android') {
    Notifications.setNotificationChannelAsync('default', {
      name: 'default',
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: '#FF231F7C',
    });
  }
 
  if (Device.isDevice) {
    const { status: existingStatus } = await Notifications.getPermissionsAsync();
    let finalStatus = existingStatus;
    if (existingStatus !== 'granted') {
      const { status } = await Notifications.requestPermissionsAsync();
      finalStatus = status;
    }
    if (finalStatus !== 'granted') {
      handleRegistrationError('Permission not granted to get push token for push notification!');
      return;
    }
    const projectId =
      Constants?.expoConfig?.extra?.eas?.projectId ?? Constants?.easConfig?.projectId;
    if (!projectId) {
      handleRegistrationError('Project ID not found');
    }
    try {
      const pushTokenString = (
        await Notifications.getExpoPushTokenAsync({
          projectId,
        })
      ).data;
      console.log(pushTokenString);
      return pushTokenString;
    } catch (e: unknown) {
      handleRegistrationError(`${e}`);
    }
  } else {
    handleRegistrationError('Must use physical device for push notifications');
  }
}

👨‍💻

Replace YOUR_EXPO_PROJECT_ID with your own Expo project ID. Find it in extra.eas.projectId in app.json or in the project settings on the Expo website.

Alternatively, retrieve projectId with the following code.

const projectId =
      Constants?.expoConfig?.extra?.eas?.projectId ??
      Constants?.easConfig?.projectId;

Notification permission prompt when the app opens

Step 3: Get an Expo Push Token 🔗

After the user grants permission, obtain an

Expo push token

. Think of it as a unique address that Expo Push Service uses to send notifications to a particular device.

Call Notifications.getExpoPushTokenAsync() to get a token object. Its data property holds the token itself, as shown in the registerForPushNotificationsAsync function above.

registerForPushNotificationsAsync()
  .then(token => 
    // sendTokenToServer(token); // 서버에 토큰 전송하는 함수 (직접 구현 필요)
  )
  .catch((error: any) => console.log(error));

Send the token to your backend and store it with the user it belongs to so that you can target that user later.

The token can change when the user reinstalls the app or switches devices. You may need to check it at each startup and update the server when it changes.

Step 4: Receive Push Notifications in the App 🔗

Once you can send notifications, decide how the app should receive and process them. The behavior differs depending on whether the app is in the foreground, in the background, or closed.

Receive Notifications in the Foreground 🔗

When a notification arrives while the user is looking at the app, a system alert does not appear by default. Use Notifications.addNotificationReceivedListener to receive the data and handle it in the app, for example by showing an in-app message.

notificationListener.current = Notifications.addNotificationReceivedListener(notification => {
  setNotification(notification);
});
return () => {
  notificationListener.current &&
    Notifications.removeNotificationSubscription(notificationListener.current);
};

To show a system-style alert in the foreground, configure Notifications.setNotificationHandler at startup with shouldShowAlert: true.

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
  }),
});

Respond When the User Taps a Notification 🔗

Decide what should happen when the user taps a system notification received while the app was closed or in the background. You might open a specific screen or show relevant data.

Use Notifications.addNotificationResponseReceivedListener. The listener runs when the user interacts with the notification. Its callback receives a response object that exposes the notification through response.notification. Use any extra server data in response.notification.request.content.data to decide what to do next. See the App component example above.

responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
  console.log(response);
});
return () => {
  responseListener.current &&
    Notifications.removeNotificationSubscription(responseListener.current);
};

Default Behavior When the App Is Closed or in the Background 🔗

When a push notification arrives while the app is closed or in the background, iOS or Android displays it through the system notification interface, such as a banner or the lock screen. Configure presentation details such as sound, badges, and Notification Center visibility at startup with Notifications.setNotificationHandler.

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
  }),
});

The operating system can restrict running complex logic as soon as a background notification arrives. A common pattern is to handle follow-up work through addNotificationResponseReceivedListener when the user taps the notification.

Step 5: Configure Native Push Notifications 🔗

The examples so far focus on testing in an Expo Go environment. Before building a

standalone app

for store distribution, complete the native push configuration for Android and iOS. Push notifications will fail in the distributed app if this setup is missing. Expo Application Services (EAS) helps manage the process.

Android: Configure FCM 🔗

Android push notifications are delivered through

Firebase Cloud Messaging (FCM)

Create a Firebase project
Create or open a project in the Google Firebase console (https://console.firebase.google.com/↗).
Add an Android app
In Firebase project settings, add an Android app with the exact package name from android.package in app.json.
Download google-services.json
Download the google-services.json file while adding the app. It contains Firebase configuration information.
Check the FCM server credentials
The Cloud Messaging tab in Firebase project settings is where the older server key was listed. For FCM V1, distinguish the client configuration in google-services.json from the service account credentials used to send notifications.
Upload credentials through EAS CLI
From the project directory, configure FCM credentials using EAS CLI. Use the Google service account key for FCM V1 and keep the client configuration in google-services.json.
```
# 아직 설치하지 않았다면: npm install -g eas-cli
eas login # Expo 계정 로그인
eas credentials 
```
Android
→ Google Service Account
→ Manage your Google Service Account for Push Notifications (FCM V1)
→ Set up a Google Service Account Key for Push Notifications (FCM V1)
→ Select the Google account

EAS uses the configured credentials when preparing your app for push notifications.

Check app.json

Make sure android.googleServicesFile points to the correct file.

app.json

{
"expo": {
  "android": {
      "googleServicesFile": "./path/to/google-services.json"
    }
  }
}

iOS: Configure APNs 🔗

iOS push notifications are delivered through

Apple Push Notification service (APNs)

Apple Developer account
You need a paid Apple Developer account.
Set the bundle identifier
Choose the app's unique bundle identifier, set ios.bundleIdentifier in app.json, and register it with Apple Developer.
Enable Push Notifications
On the Apple Developer website, enable Push Notifications for the corresponding App ID.
Create an APNs key (.p8 file)
Under Certificates, Identifiers & Profiles > Keys, create a new key with Apple Push Notifications service enabled and download the .p8 file. A certificate (.p12) is another option, but a .p8 key is recommended here. Record the Key ID and Team ID.
Upload credentials through EAS CLI
From your project directory, use EAS CLI to upload the .p8 file and the corresponding Key ID, Team ID, and bundle identifier.
```
eas credentials # 명령 실행 후 플랫폼(ios) 선택, 안내에 따라 Push Key (.p8) 파일 경로 및 관련 정보 입력
```
EAS Build uses these credentials.
Check app.json
Verify that ios.bundleIdentifier matches the value registered with Apple, and check settings such as ios.usesAppleSignIn. The aps-environment value in ios.entitlements should match the build environment, either development or production. EAS Build often handles this for you.

Native setup can look complicated at first. Follow the Expo documentation and the EAS CLI prompts as you go.

Step 6: Send a Test Notification or Send from Your Backend 🔗

Now that you have a token, you can send a push notification.

Use the Expo Push Notifications Tool 🔗

Expo's web-based tool is the quickest option during development and testing.

Open the tool
Visit https://expo.dev/notifications↗.
Enter the push token
Paste the Expo push token from your app. It looks like ExponentPushToken[...].
Write the message
Enter a title and body. You can also put extra JSON in the data field for the app to use when it receives the notification.
Send
Click Send Notification to send the message to the device associated with that token.

This lets you test how the app receives and handles a push notification before setting up a backend.

Send from a Node.js Server 🔗

In production, your backend may need to send a notification when an event occurs, such as a new message or announcement. Send an HTTP POST request to the Expo Push Service API.

Here's a simple Node.js example using fetch.

// 이 코드는 백엔드 서버(Node.js 등)에서 실행되어야 합니다.
// 절대로 앱 클라이언트 코드에 API 키나 토큰을 직접 넣지 마세요!
const sendPushNotification = async (expoPushToken, title, body, data) => {
  const message = {
    to: expoPushToken, // 알림을 받을 대상 토큰 (배열로 여러 명에게 동시 전송 가능)
    sound: 'default',  // 알림 도착 시 소리 ('default' 또는 null)
    title: title,      // 알림 제목
    body: body,        // 알림 본문
    data: data,        // 앱에서 추가적으로 사용할 데이터 (JSON 객체)
  };
  try {
    const response = await fetch('https://exp.host/--/api/v2/push/send', {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Accept-encoding': 'gzip, deflate',
        'Content-Type': 'application/json',
        // 'Authorization': `Bearer YOUR_EXPO_ACCESS_TOKEN` // Access Token 방식 사용 시 (선택 사항)
      },
      body: JSON.stringify(message),
    });
    const result = await response.json();
    console.log('Push notification sent:', result);
    // result 객체 예시: { data: { status: 'ok', id: '...' } }
    // status가 'error'인 경우 details 객체에 오류 정보 포함
    //   } catch (error) {
    console.error('Error sending push notification:', error);
  }
};
 
// 사용 예시: 저장된 사용자 토큰으로 알림 보내기
const userToken = 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]'; // 실제 사용자 토큰 사용
 
sendPushNotification(
  userToken,
  '새로운 메시지',
  '친구가 메시지를 보냈습니다!',
  { messageId: 123, sender: '친구A' } // 앱에서 활용할 추가 데이터
);

🖐️

Keep sensitive information, such as an Expo access token, out of the client app. Send authenticated API requests from a secure backend.

Customize and Manage Notifications 🔗

The expo-notifications library offers more ways to configure notifications.

Android channels
— On Android 8.0 (Oreo) and later, set up channels so users can manage settings by notification type. Use Notifications.setNotificationChannelAsync() to configure the channel ID, name, importance, and other options. See the registerForPushNotificationsAsync example above.
iOS badge count
— Read the number on the app icon with Notifications.getBadgeCountAsync() and set it with Notifications.setBadgeCountAsync(). Add logic to synchronize the count with your server.
Scheduled notifications
— Use Notifications.scheduleNotificationAsync() to schedule a local notification for later or at a recurring interval. This schedules a local notification rather than a remote push.

Conclusion 🔗

Complete code

import React, { useState, useEffect, useRef } from 'react';
import { Text, View, Button, Platform } from 'react-native';
import * as Device from 'expo-device';
import * as Notifications from 'expo-notifications';
import Constants from 'expo-constants';
 
// 앱이 실행되는 동안 알림이 도착했을 때 어떻게 처리할지 설정 (Foreground 알림 처리)
// 소리 재생, 뱃지 표시, 알림 표시 여부 등을 설정할 수 있습니다.
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true, // 알림 도착 시 사용자에게 표시할지 여부
    shouldPlaySound: true, // 소리 재생 여부
    shouldSetBadge: true,  // 뱃지 아이콘 표시 여부 (iOS)
  }),
});
 
// 푸시 알림 권한 요청 및 토큰 받기 함수
async function registerForPushNotificationsAsync() {
  // 안드로이드 채널 설정 (선택 사항이지만 권장됨)
  if (Platform.OS === 'android') {
    Notifications.setNotificationChannelAsync('default', {
      name: 'default',
      importance: Notifications.AndroidImportance.MAX, // 알림 중요도 설정
      vibrationPattern: [0, 250, 250, 250], // 진동 패턴
      lightColor: '#FF231F7C', // 알림 LED 색상
    });
  }
 
  if (Device.isDevice) {
    // 현재 권한 상태 확인
    const { status: existingStatus } = await Notifications.getPermissionsAsync();
    let finalStatus = existingStatus;
 
    // 권한이 부여되지 않았다면 요청
    if (existingStatus !== 'granted') {
      const { status } = await Notifications.requestPermissionsAsync();
      finalStatus = status;
    }
 
    // 최종적으로 권한이 거부되었다면 함수 종료
    if (finalStatus !== 'granted') {
      handleRegistrationError('Permission not granted to get push token for push notification!');
      return;
    }
 
    // 프로젝트 id 추출출
    const projectId =
      Constants?.expoConfig?.extra?.eas?.projectId ?? Constants?.easConfig?.projectId;
    if (!projectId) {
      handleRegistrationError('Project ID not found');
    }
 
    // Expo 푸시 토큰 받기
    try {
      const pushTokenString = (
        await Notifications.getExpoPushTokenAsync({
          projectId,
        })
      ).data;
      console.log(pushTokenString);
      return pushTokenString;
    } catch (e: unknown) {
      handleRegistrationError(`${e}`);
    }
  } else {
    handleRegistrationError('Must use physical device for push notifications');
  }
}
 
export default function App() {
  const [notification, setNotification] = useState<Notifications.Notification | null>(null);
  const notificationListener = useRef<Notifications.Subscription>();
  const responseListener = useRef<Notifications.Subscription>();
 
  useEffect(() => {
    // 1. 알림 권한 요청
    registerForPushNotificationsAsync()
      .then(token => 
        // sendTokenToServer(token); // 서버에 토큰 전송하는 함수 (직접 구현 필요)
      )
      .catch((error: any) => console.log(error));
 
    // 2. 알림 수신 리스너 등록 (앱 실행 중 알림 도착 시)
    notificationListener.current = Notifications.addNotificationReceivedListener(notification => {
      console.log('알림 수신 (foreground):', notification);
      setNotification(notification);
    });
 
    // 3. 알림 반응 리스너 등록 (사용자가 알림 탭 시)
    responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
      console.log('알림 반응:', response);
      // 여기서 response.notification.request.content.data 등을 통해
      // 알림에 포함된 데이터에 접근하고 특정 화면으로 이동하는 등의 로직 처리 가능
    });
 
    // 컴포넌트 unmount 시 리스너 해제
    return () => {
      if (notificationListener.current) {
        Notifications.removeNotificationSubscription(notificationListener.current);
      }
      if (responseListener.current) {
        Notifications.removeNotificationSubscription(responseListener.current);
      }
    };
  }, []);
 
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'space-around' }}>
      <Text>푸시 알림 테스트</Text>
      {/* 필요 시 버튼 등으로 알림 보내기 기능 트리거 */}
    </View>
  );
}

We walked through adding push notifications to a React Native app with Expo.

Install
expo-notifications.
Ask the user for
permission
.
Get an
Expo push token
and store it on the backend.
Send
a notification using Expo's tool or your own
server
.
Receive
the notification in the app and handle user interaction.
Finish the
native configuration
for FCM and APNs to prepare the app for distribution.

References 🔗

Expo Push Notifications Overview: https://docs.expo.dev/push-notifications/overview/↗
Using FCM for Push Notifications (Android Setup): https://docs.expo.dev/push-notifications/using-fcm/↗
Using APNs for Push Notifications (iOS Setup): https://docs.expo.dev/push-notifications/using-apns/↗
expo-notifications API Reference: https://docs.expo.dev/versions/latest/sdk/notifications/↗
EAS Credentials Documentation: https://docs.expo.dev/eas/credentials/↗

Expo Push Notifications from Setup to Delivery with expo-notifications | PromleeBlog