1---
2title: Push Notifications Overview
3sidebar_title: Overview
4---
5
6Push Notifications are an important feature, no matter what kind of app you're building. Not only is it nice to let users know about something that may interest them, be it a new album being released, a sale or other limited-time-only deal, or that one of their friends sent them a message, but push notifications are proven to help boost user interaction and create a better overall user experience.
7
8Whether you just want to be able to let users know when a relevant event happens, or you're trying to optimize customer engagement and retention, Expo makes implementing push notifications almost too easy. All the hassle with native device information and communicating with APNs (Apple Push Notification service) or FCM (Firebase Cloud Messaging) is taken care of behind the scenes, so that you can treat iOS and Android notifications the same, saving you time on the front-end, and back-end!
9
10There are three main steps to setting up push notifications, and we provide a guide for each part of the process:
11
12- [Setup: getting a user's Expo Push Token](push-notifications-setup.mdx)
13- [Sending: calling Expo's Push API with the token when you want to send a notification](sending-notifications.mdx)
14- [Receiving: responding to the notification in your app](receiving-notifications.mdx) (maybe upon opening, you want to jump to a particular screen that the notification refers to)
15
16## Usage
17
18The code below shows a full example of how to register for, send, and receive push notifications in a React Native app. But make sure to read the rest of the guide, so that you understand how Expo's push notification service works, what the best practices are, and how to investigate any problems you run into!
19
20```js
21import * as Device from 'expo-device';
22import * as Notifications from 'expo-notifications';
23import React, { useState, useEffect, useRef } from 'react';
24import { Text, View, Button, Platform } from 'react-native';
25
26Notifications.setNotificationHandler({
27  handleNotification: async () => ({
28    shouldShowAlert: true,
29    shouldPlaySound: false,
30    shouldSetBadge: false,
31  }),
32});
33
34export default function App() {
35  const [expoPushToken, setExpoPushToken] = useState('');
36  const [notification, setNotification] = useState(false);
37  const notificationListener = useRef();
38  const responseListener = useRef();
39
40  useEffect(() => {
41    registerForPushNotificationsAsync().then(token => setExpoPushToken(token));
42
43    // This listener is fired whenever a notification is received while the app is foregrounded
44    notificationListener.current = Notifications.addNotificationReceivedListener(notification => {
45      setNotification(notification);
46    });
47
48    // This listener is fired whenever a user taps on or interacts with a notification (works when app is foregrounded, backgrounded, or killed)
49    responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
50      console.log(response);
51    });
52
53    return () => {
54      Notifications.removeNotificationSubscription(notificationListener.current);
55      Notifications.removeNotificationSubscription(responseListener.current);
56    };
57  }, []);
58
59  return (
60    <View
61      style={{
62        flex: 1,
63        alignItems: 'center',
64        justifyContent: 'space-around',
65      }}>
66      <Text>Your expo push token: {expoPushToken}</Text>
67      <View style={{ alignItems: 'center', justifyContent: 'center' }}>
68        <Text>Title: {notification && notification.request.content.title} </Text>
69        <Text>Body: {notification && notification.request.content.body}</Text>
70        <Text>Data: {notification && JSON.stringify(notification.request.content.data)}</Text>
71      </View>
72      <Button
73        title="Press to Send Notification"
74        onPress={async () => {
75          await sendPushNotification(expoPushToken);
76        }}
77      />
78    </View>
79  );
80}
81
82// Can use this function below, OR use Expo's Push Notification Tool-> https://expo.dev/notifications
83async function sendPushNotification(expoPushToken) {
84  const message = {
85    to: expoPushToken,
86    sound: 'default',
87    title: 'Original Title',
88    body: 'And here is the body!',
89    data: { someData: 'goes here' },
90  };
91
92  await fetch('https://exp.host/--/api/v2/push/send', {
93    method: 'POST',
94    headers: {
95      Accept: 'application/json',
96      'Accept-encoding': 'gzip, deflate',
97      'Content-Type': 'application/json',
98    },
99    body: JSON.stringify(message),
100  });
101}
102
103async function registerForPushNotificationsAsync() {
104  let token;
105  if (Device.isDevice) {
106    const { status: existingStatus } = await Notifications.getPermissionsAsync();
107    let finalStatus = existingStatus;
108    if (existingStatus !== 'granted') {
109      const { status } = await Notifications.requestPermissionsAsync();
110      finalStatus = status;
111    }
112    if (finalStatus !== 'granted') {
113      alert('Failed to get push token for push notification!');
114      return;
115    }
116    token = (await Notifications.getExpoPushTokenAsync()).data;
117    console.log(token);
118  } else {
119    alert('Must use physical device for Push Notifications');
120  }
121
122  if (Platform.OS === 'android') {
123    Notifications.setNotificationChannelAsync('default', {
124      name: 'default',
125      importance: Notifications.AndroidImportance.MAX,
126      vibrationPattern: [0, 250, 250, 250],
127      lightColor: '#FF231F7C',
128    });
129  }
130
131  return token;
132}
133```
134
135## Testing
136
137We recommend testing push notifications on a physical device. iOS simulators **cannot** receive push notifications, and neither can Android emulators unless you are running an image with Google Play Services installed and configured. Additionally, when calling `Notifications.requestPermissionsAsync()` on the simulator, it will resolve immediately with `undetermined` as the status, regardless of whether you choose to allow or not.
138
139The [Expo push notification tool](https://expo.dev/notifications) is also useful for testing push notifications during development. It lets you easily send test notifications to your device, without having to use your CLI or write out a test server.
140
141## Next steps
142
143Read through the [notification setup guide](./push-notifications-setup.mdx) to get your credentials setup, and start collecting push tokens!
144
145## See also
146
147- Having trouble? Visit [Expo's notification FAQ page](./faq.mdx)
148