Push Notifications Troubleshooting & FAQ
This is a collection of FAQs and common issues when setting up push notifications with Expo. This document covers the expo-notifications
client-side library, as well as Expo's push notification service.
There is no cost associated with sending notifications through Expo's classic push notification service. EAS Notify, a push notification service with new features coming in 2021, will be part of EAS's pricing plans.
We don't impose any limit on the number of push notifications you can send. For best results, we do recommend you add throttling (handled automatically in the
expo-server-sdk-node
) and retry logic to your server.
Total notifications is much less important than your maximum notification throughput—how many notifications you send per second at peak. If this number is more than a couple hundred, reach out to us because we'd love to hear about what you're working on!
You should read all the relevant guides (this won't take longer than 10 minutes):
That being said, we think sending notifications through Expo is the fastest and easiest way to do it, and millions of notifications are sent through Expo every day.
Push notifications have a lot of moving parts, so this can be due to a wide variety of reasons. To narrow things down, check the
push ticket and
push receipt for error messages. This information (and maybe a little bit of Googling) will help narrow down the problem so that you can solve it.
You can also narrow things even further by testing
local notifications in your app. This will ensure all of your client-side logic is correct, and narrow things down to the server side or app credentials.
1. Send a notification:
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{
"to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
"title":"hello",
"body": "world"
}'
- Use the resulting ticket
id
to request the push receipt:
curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{
"ids": [
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
]
}'
The
ExpoPushToken
will remain the same across app upgrades, and
eject
ing to the bare workflow. On iOS, it will also remain the same even after uninstalling the app and reinstalling (on Android, this results in the push token changing). It will also change if you change your
applicationId
or
experienceId
(usually
@expoUsername/projectSlug
).
The ExpoPushToken
will never "expire" but if one of your users uninstalls the app, you'll receive a DeviceNotRegistered
error back from Expo's servers, meaning you should stop sending notifications to this app.
This strongly indicates that you have either misconfigured your credentials, or didn't configure them at all. In the Expo client app, you rely on Expo's credentials so that you don't need to worry about it, and setup is as easy as possible. But when you build your own app for the stores, you need to use your own credentials. On iOS, this is handled via your
push key (revoking the push key associated with your app
will result in your notifications failing to be delivered. To fix that, add a new push key with
expo credentials:manager
). On Android, all you need to do is follow
this guide.
Please note that after setting up Android FCM credentials, you will need to rebuild your app.
Expo abstracts the majority of credential management away so that you can focus on building your app, but if you want to understand it on a deeper level, read our
guide to app signing.
This is likely due to the
priority
level of the notifications you're sending. You can learn more about Android priority
here, but as for how it relates to Expo-
Expo accepts four priorities:
default
: manually mapped to the default priority documented by Apple and Googlehigh
: mapped to the high priority level documented by Apple and Googlenormal
: mapped to the normal priority level documented by Apple and Google- (priority omitted): treated exactly as if
default
were specified
And setting the priority to high
gives your notification the greatest likelihood that the Android OS will display the notification.
Expo does not store the contents of push notifications any longer than it takes to deliver the notifications to the push notification services operated by Apple, Google, etc... Push notifications are stored only in memory and in message queues and not stored in databases.
Expo does not read or share the contents of push notifications and our services keep push notifications only as long as needed to deliver them to push notification services run by Apple and Google. If the Expo team is actively debugging the push notifications service, we may see notification contents (ex: at a breakpoint) but Expo cannot see push notification contents otherwise.
Expo's connections to Apple and Google are encrypted and use HTTPS.
When your push notification credentials have expired, run expo credentials:manager -p ios
which will provide a list of actions to choose from. Select the removal of your expired credentials and then select "Add new Push Notifications Key".
Expo makes a best effort to deliver notifications to the push notification services operated by Apple and Google. Expo's infrastructure is designed for at-least-once delivery to the underlying push notification services; it is more likely for a notification to be delivered to Apple or Google more than once rather than not at all, though both are uncommon but possible.
After a notification has been handed off to an underlying push notification service, Expo creates a "push receipt" that records whether the handoff was successful; a push receipt denotes whether the underlying push notification service received the notification.
Finally, the push notification services from Apple, Google, etc... make a best effort to deliver the notification to the device according to their own policies.
This indicates an issue with the image asset you're providing. The image should be all white with a transparent background (this is required and enforced by Google, not Expo).
See here for more information.