有关 Expo 推送通知服务的常见问题集合。
使用 expo-notifications 库和 Expo 的推送通知服务设置推送通知时的常见问题和常见问题解答的集合。
¥A collection of common issues and FAQs when setting up push notifications with the expo-notifications library and Expo's push notification service.
¥Expo's push notification service
¥Cost of the push notification service
通过 Expo 的经典推送通知服务发送通知不需要任何费用。
¥There is no cost associated with sending notifications through Expo's classic push notification service.
¥Limit of sending notifications
每个项目每秒可发送的通知数上限为 600 个。如果超过此速率，后续请求将失败，直到速率再次低于每秒 600 个。
¥There is a limit of 600 notifications per second per project that can be sent. If you exceed this rate, subsequent requests will fail until the rate falls below 600 per second again.
为了获得最佳结果，我们建议你向服务器添加限制（在 expo-server-sdk-node 中自动处理）和重试逻辑。
¥For best results, we recommend you add throttling (which is handled automatically in the expo-server-sdk-node) and retry logic to your server.
¥Using Expo's push notification service is not mandatory
你可以使用 Expo 项目的任何推送通知服务。expo-notifications 的 getDevicePushTokenAsync 方法 允许你获取原生设备推送令牌，然后你可以将其与其他服务甚至 直接通过 FCM 和 APN 发送通知 一起使用。
¥You can use any push notification service for Expo projects. The getDevicePushTokenAsync method from expo-notifications allows you to get the native device push token, which you can then use with other services, or even send your notifications directly through FCM and APNs.
¥Connections to notification service are encrypted
Expo 与 Apple 和 Google 的连接已加密并使用 HTTPS。
¥Expo's connections to Apple and Google are encrypted and use HTTPS.
¥Contents of the notification are not stored
Expo 存储推送通知内容的时间不会超过将通知发送到 Apple、Google 等运营的推送通知服务所需的时间。通知仅存储在内存和消息队列中，不存储在数据库中。
¥Expo doesn't store the contents of push notifications any longer than it takes to deliver the notifications to the push notification services operated by Apple, Google, and so on. Notifications are stored only in memory and in message queues and not stored in databases.
¥Contents of the notifications may be seen by Expo staff
如果 Expo 团队正在积极调试推送通知服务，我们可能会看到通知内容（例如，在断点处），但 Expo 否则无法看到推送通知内容。
¥If the Expo team is actively debugging the push notifications service, we may see notification contents (for example, at a breakpoint) but Expo cannot see push notification contents otherwise.
¥Delivery guarantees
Expo 尽最大努力向 Google 和 Apple 运营的推送通知服务发送通知。Expo 的基础设施旨在至少向底层推送通知服务传递一次。在某些情况下，通知可能会多次发送给 Google 或 Apple，或者根本不会发送，尽管这种情况很少见。
¥Expo makes the best effort to deliver notifications to the push notification services operated by Google and Apple. Expo's infrastructure is designed for at-least-once delivery to the underlying push notification services. In some cases, a notification may be delivered to Google or Apple more than once or not at all, although these cases are rare.
将通知移交给底层推送通知服务后，Expo 会创建一个 "推送收据" 来记录移交是否成功。推送收据表示底层推送通知服务是否收到通知。
¥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.
最后，Google、Apple 等的推送通知服务遵循其策略将通知传递到设备。
¥Finally, the push notification services from Google, Apple, and so on follow their policies to deliver the notification to the device.
¥Push notifications
¥Notifications aren't working
推送通知有很多移动部分，因此这可能是由于多种原因造成的。要缩小范围，请检查 推票 和 推送收据 是否有错误消息。
¥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.
你还可以通过在应用中测试 本地通知 来进一步缩小范围。这将确保所有客户端逻辑都是正确的，并将范围缩小到服务器端或应用凭据。
¥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.
发送通知：
¥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"
}'
使用生成的票证 id 请求推送收据：
¥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"
]
}'
ExpoPushToken 何时以及为何改变¥When and why does the ExpoPushToken change
ExpoPushToken 在应用升级中将保持不变。在 iOS 上，即使卸载应用并重新安装后，它也将保持不变。在 Android 上，这会导致推送令牌发生变化。
¥The ExpoPushToken will remain the same across app upgrades. On iOS, it will also remain the same even after uninstalling the app and reinstalling it. On Android, this results in the push token changing.
如果你更改 applicationId 或 experienceId（通常是 @expoUsername/projectSlug），它也会更改。
¥It will also change if you change your applicationId or experienceId (usually @expoUsername/projectSlug).
ExpoPushToken 永远不会过期。但是，如果你的一位用户卸载了该应用，你将从 Expo 的服务器返回 DeviceNotRegistered 错误。这意味着你应该停止向此应用发送通知。
¥The ExpoPushToken will never expire. However, if one of your users uninstalls the app, you'll receive a DeviceNotRegistered error back from Expo's servers. This means you should stop sending notifications to this app.
¥Notifications work in development, but not after building the app
这表明你的凭据配置错误或者根本没有在生产应用中配置它们。Expo Go 使用 Expo 的凭证，允许在开发中处理通知。
¥This indicates that you have either misconfigured your credentials or didn't configure them at all in your production app. Expo Go uses Expo's credentials, which allows working on notifications in development.
当你为应用商店构建应用时，你需要生成并使用自己的凭据。在 Android 上，请遵循 本指南。在 iOS 上，这由你的 按键 处理（撤销与你的应用关联的推送键将导致你的通知无法发送。要解决此问题，请使用 eas credentials 添加新的推送键）。
¥When you build your app for the app stores, you need to generate and use your own credentials. On Android, follow this guide. On iOS, this is handled by 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 eas credentials).
欲了解更多信息，请参阅 应用签名。
¥For more information, see app signing.
¥Notifications occasionally stop coming through on Android
这可能是由于你发送的通知的 priority 级别所致。你可以了解更多有关 安卓优先 的信息。Expo 接受四个优先事项：
¥This is likely due to the priority level of the notifications you're sending. You can learn more about Android priority. Expo accepts four priorities:
default：手动映射到 Apple 和 Google 记录的默认优先级
¥default: manually mapped to the default priority documented by Apple and Google
high：映射到 Apple 和 Google 记录的高优先级
¥high: mapped to the high priority level documented by Apple and Google
normal：映射到 Apple 和 Google 记录的正常优先级
¥normal: mapped to the normal priority level documented by Apple and Google
（优先级省略）：完全按照指定 default 的方式处理
¥(priority omitted): treated exactly as if default were specified
将优先级设置为 high 可以让 Android 最有可能显示该通知。
¥And setting the priority to high gives your notification the greatest likelihood that the Android will display the notification.
¥Handle expired push notification credentials
当你的推送通知凭据过期时，运行 eas credentials，选择 iOS 和构建配置文件，然后删除推送通知密钥并生成一个新密钥。
¥When your push notification credentials have expired, run eas credentials, choose iOS and a build profile, then remove your push notification key and generate a new one.
¥Error message when sending a notification
检查返回的推送票证或收据的 details 属性以获取更多信息。读这个 用于常见错误代码响应及其相关解决方案。
¥Check the details property of the returned push ticket or receipt for more information. Read this for common error code responses and their associated solutions.
¥Fetching a push token takes a long time on iOS
在 iOS 上，getDevicePushTokenAsync 和 getExpoPushTokenAsync 有时可能需要很长时间才能解析。正如 Apple 的 推送通知故障排除 技术说明中所述，这超出了 expo-notifications 的控制范围：
¥getDevicePushTokenAsync and getExpoPushTokenAsync can sometimes take a long time to resolve on iOS. This is outside of expo-notifications's control, as stated in Apple's Troubleshooting Push Notifications technical note:
这不一定是错误情况。该系统可能根本没有互联网连接，因为它超出了任何手机信号塔或 Wi-Fi 接入点的范围，或者它可能处于飞行模式。你的应用不应将其视为错误，而应正常继续，仅禁用依赖推送通知的功能。
¥This is not necessarily an error condition. The system may not have Internet connectivity at all because it is out of range of any cell towers or Wi-Fi access points, or it may be in airplane mode. Instead of treating this as an error, your app should continue normally, disabling only that functionality that relies on push notifications.
以下是我们的社区成员解决此问题的一些方法：
¥Here are some ways our community members have resolved this issue:
阅读苹果的 有关推送通知故障排除的技术说明！这是有关此问题的最可靠的信息来源。为了帮助你理解他们的建议：
¥Read Apple's Technical Note on troubleshooting push notifications! This is the single most reliable source of information on this problem. To help you grasp what they're suggesting:
确保设备与互联网有可靠的连接（尝试关闭 Wi-Fi 或切换到另一个网络，并禁用端口 5223 上的防火墙阻止，如 这个答案 中的建议）。
¥Make sure the device has a reliable connection to the Internet (try turning off Wi-Fi or switching to another network, and disabling the firewall block on port 5223, as suggested in this SO answer).
裸 React Native 应用必须 手动启用推送通知功能。如果你在设置时遇到问题，请参阅 这个 Stack Overflow 答案。你可能还想尝试通过记录 这个 Stack Overflow 答案 概述的持久连接调试信息来进一步调试此问题。
¥Bare React Native apps must manually enable the Push Notifications capability. If you have trouble setting this up, refer to this Stack Overflow answer. You may also want to try to debug this even further by logging persistent connection debug information as outlined by this Stack Overflow answer.
设备附近的 APNS 服务器可能已关闭，如 这个论坛主题 所示。散散步，稍后再试！
¥APNS servers near the device may be down as indicated by this forum thread. Take a walk and try again later!
按照 这个 GitHub 评论 的建议，过几天再试一次。
¥Try again in a few days as suggested by this GitHub comment.
你可能需要禁用网络共享，因为这可能会影响 这个 Stack Overflow 答案 建议的注册。
¥You may need to disable network sharing as this may impact the registration as suggested by this Stack Overflow answer.
如果你刚刚更改了应用应注册的 APNS 服务器（通过在同一设备上的 Xcode 版本上安装 TestFlight 版本），你可能需要按照 这个 Stack Overflow 答案 的建议重新启动设备。
¥If you just changed the APNS servers where the app should be registering (by installing a TestFlight build over an Xcode build on the same device) you may need to restart your device as suggested by this Stack Overflow answer.
如果你遇到此问题的设备尚未安装 SIM 卡，那么按照 这个 Stack Overflow 答案 的建议进行配置可能有助于缓解此错误。
¥If the device you're experiencing this on hasn't been setup with a SIM card it looks like configuring it may help mitigate this bug as suggested by this Stack Overflow answer.
¥Miscellaneous
¥Sending notifications directly through FCM and APNs
如果你不使用 Expo 推送通知服务，而是想直接与 Google 和 Apple 通信，请参阅 使用 FCM 和 APN 发送通知，特别注意有效负载格式，因为提供不同的格式可能会导致两个平台上出现意外行为。
¥If you are not using Expo's push notification service and instead, would like to communicate with Google and Apple directly, see Send notifications with FCM and APNs, paying special attention to the payload formats, since providing different formats can result in unexpected behavior on both platforms.
¥Notification icon on Android is a grey or white square
这表明你提供的图片资源存在问题。图片应为全白色并具有透明背景（这是 Google 而非 Expo 所要求和强制执行的）。欲了解更多信息，请参阅 本文。
¥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). For more information, see this article.
¥Play a custom sound when I send a notification
Expo 推送通知服务目前不支持自定义声音。你将需要在独立应用中直接将 FCM 和 APN 与从 expo-notifications 收到的原生设备令牌结合使用。
¥The Expo push notification service currently doesn't support custom sounds. You will need to use FCM and APNs directly with the native device tokens received from expo-notifications in standalone apps.
LegacyNotifications 库迁移¥Migrate from Expo's LegacyNotifications library
有关如何从 Expo 的 LegacyNotifications 库迁移到使用 expo-notifications 的更多信息，请参阅 迁移指南。
¥For more information on how to migrate from Expo's LegacyNotifications library to use expo-notifications, see the migration guide.