你需要了解的有关通知的信息

在开始之前，了解通知类型及其行为。

通知是用于在应用未处于活动状态时向用户告知新信息或事件的提醒。它们的覆盖范围很大，不同平台之间的差异可能会使实现通知变得令人望而生畏。

🌐 Notifications are alerts that inform users of new information or events, even when the app isn't actively in use. They have a large surface area and differences across platforms can make implementing notifications intimidating.

无论你是刚开始使用通知还是已有相关知识，本文档都将解释不同类型的通知及其行为。

🌐 Whether you are starting with notifications or have existing knowledge, this document explains the different types of notification and their behaviors.

Expo 的通知支持建立在 Android 和 iOS 提供的原生功能之上。原生平台的相同概念和行为同样适用于 Expo 应用。如果你不确定某个特定的通知功能，请参阅各个平台的官方文档。

🌐 Expo's notification support builds on top of the native functionality provided by Android and iOS. The same concepts and behaviors from native platforms apply to Expo apps. If you are unsure about a specific notification feature, see each platform's official documentation.

远程和本地通知

🌐 Remote and Local notifications

1. 推送通知：（也称为“远程通知”）是从远程服务器发送到用户设备的通知。
2. 本地通知：（也称为“应用内通知”）由应用内部创建和显示的通知。由于许多用于创建这些通知的 API 会在特定时间创建它们，因此这些通知有时也被称为“定时通知”。

expo-notifications 支持推送通知和本地通知。由于此功能未内置在 Expo Go 中，因此你必须使用 开发版本 才能使用推送通知。

请参见应用内通知了解如何创建和显示本地通知。本指南的其余部分将重点介绍推送通知。

🌐 See in-app notifications on how to create and display a local notification. The rest of this guide focuses on push notifications.

推送通知传递

🌐 Push Notification delivery

当推送通知到达你的应用时，其行为取决于应用的状态和通知的类型。让我们来澄清一下术语：

🌐 When a push notification arrives to your app, its behavior depends on the app's state and the type of notification. Let's clarify the terminology:

应用状态

🌐 Application states

• 前台：该应用正在前台运行。其界面当前显示在屏幕上。
• 背景：该应用正在后台运行，即“最小化”状态。其界面当前未显示在屏幕上。
• 已终止：应用已被“关闭”，通常是在应用切换器中通过滑动手势进行的。在 Android 上，如果用户从设备设置中强行停止应用，则必须手动重新打开应用，通知才能开始工作（这是 Android 的限制）。

推送通知行为

🌐 Push Notification behaviors

对于任何类型的通知，当应用处于前台时，应用可以控制如何处理接收到的通知。应用可以直接展示通知、显示一些自定义的应用内界面，甚至忽略通知（这由 NotificationHandler 控制）。当应用不在前台时，行为取决于通知的类型。

🌐 For any kind of notification, when the app is in the foreground, the app is in control of how an incoming notification is handled. The app may present it directly, show some custom in-app UI, or even ignore it (this is controlled by NotificationHandler). When the app is not in the foreground, the behavior depends on the type of notification.

下表总结了将推送通知发送到设备时发生的情况：

🌐 The table below summarizes what happens when a push notification is delivered to the device:

对于用户与通知交互的情况（例如，按下操作按钮），你可以使用以下处理程序。

🌐 For the cases when the user interacts with the notification (for example, by pressing an action button), the following handlers are made available to you.

在上表中，每当触发 NotificationResponseReceivedListener 时，useLastNotificationResponse 的返回值也会发生变化。

🌐 In the table above, whenever NotificationResponseReceivedListener is triggered, also useLastNotificationResponse return value would change.

信息 当应用未运行或被终止时，通过点击通知启动应用，NotificationResponseReceivedListener 应该在模块顶层尽早注册，以便在 iOS 上触发。对于将应用带到前台的操作按钮，我们建议在应用启动后使用 useLastNotificationResponse 或 getLastNotificationResponse 捕获响应。

推送通知类型

🌐 Push Notification types

通知消息

🌐 Notification Message

通知消息是一种指定演示信息（例如标题或正文）的通知。

🌐 A Notification Message is a notification that specifies presentational information, such as a title or body text.

• 在 Android 上，这对应于包含 AndroidNotification 的推送通知请求
• 在 iOS 上，这对应于包含 aps.alert 字典 且 apns-push-type 头设置为 alert 的推送通知请求。

当你使用 Expo 推送服务，并指定 title、subtitle、body、icon 或 channelId 时，生成的推送通知请求是通知消息。

🌐 When you use the Expo Push Service, and specify title, subtitle, body, icon, or channelId, the resulting push notification request is a Notification Message.

通知消息的典型用例是立即将其渲染给用户，而无需进行任何额外处理。

🌐 The typical use case for a Notification Message is to have it presented to the user immediately without any extra processing being done.

带有数据负载的通知消息

🌐 Notification Message with data payload

这是一个仅限 Android 的术语（参见官方文档），其中推送通知请求同时包含 data 字段和 notification 字段。

🌐 This is an Android-only term (see the official docs) where a push notification request contains both data field and a notification field.

在 iOS 上，额外数据可能是常规通知消息请求的一部分。Apple 并不区分携带数据与不携带数据的通知消息。

🌐 On iOS, extra data may be part of a regular Notification Message request. Apple doesn't distinguish between Notification Message which does and does not carry data.

无头后台通知

🌐 Headless Background Notifications

无界面通知是一种远程通知，它不会直接指定诸如标题或正文之类的展示信息。除下列情况外*，无界面通知不会向用户呈现。相反，它们携带数据（JSON），由你在应用中通过 registerTaskAsync 定义的 JavaScript 任务进行处理。该任务可以执行任意逻辑。例如，写入 AsyncStorage、发起 API 请求，或者呈现一个本地通知，其内容来自推送通知的数据。

🌐 Headless Notification is a remote notification that doesn't directly specify presentational information such as the title or body text. With the exception below*, headless notifications are not presented to users. Instead, they carry data (JSON) which is processed by a JavaScript task defined in your app via registerTaskAsync. The task may perform arbitrary logic. For example, write to AsyncStorage, make an api request, or present a local notification whose content is taken from the push notification's data.

信息 我们使用“无界面后台通知”一词来指代 Android 上的 数据消息 和 iOS 上的 后台通知。它们的主要相似点是，这两种通知类型都只允许发送 JSON 数据，并且可以由应用进行后台处理。

无头后台通知能够在收到通知时运行自定义 JavaScript，即使应用已被终止。这很强大，但也有一个限制：即使通知已送达设备，操作系统也不保证它会送达你的应用。这可能由于多种原因发生，例如当 Android 上启用休眠模式，或者当你发送过多后台通知时——Apple 建议每小时不要发送超过两到三条。

🌐 Headless Background Notifications have the ability to run custom JavaScript in response to a notification even when the app is terminated. This is powerful but comes with a limitation: even when the notification is delivered to the device, the OS does not guarantee its delivery to your app. This may happen due to a variety of reasons, such as when Doze mode is enabled on Android, or when you send too many background notifications — Apple recommends not to send more than two or three per hour.

当你使用 Expo 推送服务，并且只指定 data 和 _contentAvailable: true（以及其他非交互字段如 ttl）时，产生的推送通知请求会生成无界面后台通知。

🌐 When you use the Expo Push Service, and specify only data and _contentAvailable: true (and other non-interactive fields such as ttl), the resulting push notification request produces a Headless Background Notification.

要在 iOS 上使用无界面后台通知，你必须先进行配置。

经验法则是，如果你不需要在后台运行 JavaScript，则最好使用常规通知消息。

🌐 The rule of thumb is to prefer a regular Notification Message if you don't require running JavaScript in the background.

• 唯一的例外是当你在 data 中指定 title 或 message 时。在这种情况下，expo-notifications 包会在 Android 上自动显示无头通知，但在 iOS 上不会。我们计划在未来的版本中使这一行为在各个平台上更一致。

仅数据通知

🌐 Data-only notifications

Android 有一个 数据消息 的概念。iOS 并没有完全相同的概念，但一个接近的等效是 无界面后台通知。

🌐 Android has a concept of Data Messages. iOS does not have exactly the same concept, but a close equivalent is Headless Background Notifications.

你可能还会遇到“静默通知”这个术语，它是指不会向用户显示任何内容的通知——我们将其称为无界面后台通知。

🌐 You may also come across the term "silent notification", which is yet another name for notifications that don't present anything to the user — we describe these as Headless Background Notifications.

外部参考

🌐 External references

这是 Android 和 iOS 上推送通知的官方资源的非详尽列表：

🌐 This is a non-exhaustive list of official resources for push notifications on Android and iOS:

• Android - Firebase 云消息传递消息类型
• iOS - 生成远程通知
• iOS - 向你的应用推送后台更新