通知的桥接选项
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
默认情况下,通知会从手机上的应用桥接(共享)到配对手表。如果您构建的手表应用也同时存在于配对手机上,用户可能会收到重复的通知:一个由电话应用生成和桥接,另一个由手表应用生成。您可以利用 Wear OS 提供的功能来控制桥接通知的方式和时间。
避免显示重复的通知
如果您使用外部来源(例如 Firebase Cloud Messaging)来创建通知,您的移动应用和穿戴式应用就可能会各自在手表上显示自己的通知。若要避免此类重复通知,请在穿戴式应用中以程序化方式停用桥接功能。
如果您想在穿戴式应用安装后,将移动应用中创建的部分通知桥接到手表,请设置桥接标记。
您可以使用 setBridgeTag(String)
方法为通知设置桥接标记,如以下代码示例所示:
val notification = NotificationCompat.Builder(context, channelId)
// ... set other fields ...
.extend(
NotificationCompat.WearableExtender()
.setBridgeTag("tagOne")
)
.build()
停用桥接功能
您可以为某些通知或所有通知停用桥接功能。建议您有选择地停用桥接功能。
为某些通知停用桥接功能
您可以动态停用桥接功能,并视需要根据通知的标记允许显示某些通知。例如,如需停用除了标记 tagOne
、tagTwo
或 tagThree
之外所有通知的桥接功能,请使用 BridgingConfig
对象,如以下示例所示:
BridgingManager.fromContext(context).setConfig(
BridgingConfig.Builder(context, false)
.addExcludedTags(listOf("tagOne", "tagTwo", "tagThree"))
.build()
)
为所有通知停用桥接功能(不推荐)
注意:不建议为所有通知停用桥接功能,因为清单中设置的桥接配置会在安装手表应用后立即生效。如果用户需要先打开并设置手表应用,然后才能收到通知,则此配置可能会导致通知丢失。
为了避免桥接来自手机应用的所有通知,请在手表应用的清单文件中使用 <meta-data>
条目,如以下示例所示:
<application>
...
<!-- Beware, this can have unintended consqequences before the user is signed-in -->
<meta-data
android:name="com.google.android.wearable.notificationBridgeMode"
android:value="NO_BRIDGING" />
...
</application>
注意:在运行时指定桥接配置会替换 Android 清单文件中与桥接有关的设置。
设置关闭 ID 以同步类似通知
如果您使用桥接模式功能阻止桥接功能,通知关闭行为就不会在用户的各设备间同步。
不过,如果在移动设备和手表上都创建了类似的通知,则建议您在用户关闭其中任一设备上的通知后,让系统同时关闭两边的通知。
您可以在 NotificationCompat.WearableExtender
中设置全局唯一 ID,以便在其中一条通知关闭后,配对手表上具有相同 ID 的其他通知也会关闭。
NotificationCompat.WearableExtender
类提供了一些方法,可让您使用关闭 ID,如以下示例所示:
fun setDismissalId(dismissalId: String): WearableExtender
fun getDismissalId(): String
如需同步关闭行为,请使用 setDismissalId()
方法。当您调用 setDismissalId()
方法时,为每条通知传递一个字符串形式的全局唯一 ID。
相应通知关闭后,手表和手机上具有相同关闭 ID 的所有其他通知也会关闭。如需检索关闭 ID,请使用 getDismissalId()
。
在以下示例中,由于为新通知指定了全局唯一 ID,因此关闭行为会进行同步:
val notification = NotificationCompat.Builder(context, channelId)
// Set other fields ...
.extend(
NotificationCompat.WearableExtender()
.setDismissalId("abc123")
)
.build()
注意:关闭 ID 在手表与 Android 手机配对的情况下有效,但在手表与 iPhone 配对的情况下无效。
不桥接通知的情况
以下类型的通知不会被桥接:
桥接通知最佳实践
从穿戴式设备推送或移除桥接通知需要花费一定时间。在设计通知时,一定要避免由这一延迟造成的意外行为。以下准则有助于确保桥接通知能与异步通知一起使用:
-
如果您取消了手机上的某条通知,手表上的对应通知可能需要过一段时间才会取消。在此期间,用户可能会发送该通知上的某个待处理 intent。因此,请继续在应用中接收其已取消的通知的待处理 intent:取消通知时,请保证这些通知的待处理 intent 接收器有效。
-
请勿一次取消并重新触发堆叠的所有通知。只修改或移除已实际发生修改的通知。这样可以避免在更新穿戴式设备时出现延迟,并降低应用对电池续航时间的影响。
设计注意事项
Wear OS 通知有自己的设计准则。如需了解详情,请参阅 Wear OS 设计指南。
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-26。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-07-26。"],[],[],null,["# Bridging options for notifications\n\nBy default, notifications are bridged, or shared, from an app on a phone to any paired watches. If\nyou build a watch app and your app also exists on a paired phone, users might receive duplicate\nnotifications---one generated and bridged by the phone app and one generated\nby the watch app. Wear OS includes features to control how and when\nnotifications are bridged.\n\nAvoid duplicate notifications\n-----------------------------\n\n\nWhen you create notifications from an external source, such as from\n[Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/), your\nmobile app and your wearable app can each display its own notifications on the watch. To avoid\nthis sort of duplication, programmatically disable bridging in your wearable app.\n\n### Use bridge tags\n\n\nIf you want to bridge some of the notifications created on your mobile app to the watch\nwhen your wearable app is installed, set bridge tags.\n\n\nSet a bridge tag on a notification by using the\n[setBridgeTag(String)](/reference/androidx/core/app/NotificationCompat.WearableExtender#setBridgeTag(java.lang.String))\nmethod, as shown in the following code sample:\n\n```kotlin\nval notification = NotificationCompat.Builder(context, channelId)\n // ... set other fields ...\n .extend(\n NotificationCompat.WearableExtender()\n .setBridgeTag(\"tagOne\")\n )\n .build()\n```\n\n### Disable bridging\n\nYou can disable bridging for some notifications or for all notifications.\nWe recommend that you selectively disable bridging.\n\n#### Disable bridging for *some* notifications\n\n\nYou can dynamically disable bridging and, optionally, permit some notifications\nthrough based on their tag. For example, to disable bridging for all notifications except those tagged as\n`tagOne`, `tagTwo`, or `tagThree`, use the\n[BridgingConfig](/reference/androidx/wear/phone/interactions/notifications/BridgingConfig)\nobject as shown in the following example: \n\n```kotlin\nBridgingManager.fromContext(context).setConfig(\n BridgingConfig.Builder(context, false)\n .addExcludedTags(listOf(\"tagOne\", \"tagTwo\", \"tagThree\"))\n .build()\n)\n```\n\n#### Disable bridging for *all* notifications (not recommended)\n\n\n**Note:** Disabling bridging for all notifications is not recommended, because\nthe bridging configuration set in the manifest takes effect as soon as a watch app is installed.\nThis can lead to notifications being lost if the user needs to open and set up the watch app\nbefore receiving notifications.\n\n\nTo prevent bridging of all notifications from a\nphone app, use the `\u003cmeta-data\u003e` entry in the manifest file of the watch app, as shown in the following example: \n\n```xml\n\u003capplication\u003e\n...\n \u003c!-- Beware, this can have unintended consqequences before the user is signed-in --\u003e\n \u003cmeta-data\n android:name=\"com.google.android.wearable.notificationBridgeMode\"\n android:value=\"NO_BRIDGING\" /\u003e\n...\n\u003c/application\u003e\n```\n\n\n**Note:** Specifying a bridging configuration at runtime overrides a bridging-related\nsetting in the Android manifest file.\n\n### Set a dismissal ID to sync similar notifications\n\n\nWhen you prevent bridging with the bridging mode feature, dismissals of notifications are not\nsynced across a user's devices.\n\n\nHowever, if similar notifications are created on both the mobile device and the watch, you want both\nnotifications to be dismissed when the user dismisses either one of them.\n\n\nIn the\n[NotificationCompat.WearableExtender](/reference/androidx/core/app/NotificationCompat.WearableExtender),\nyou can set a global unique ID so that when a notification dismisses, other notifications\nwith the same ID on paired watches are also dismissed.\n\n\nThe\n`NotificationCompat.WearableExtender`\nclass has methods that let you use dismissal IDs, as shown in the following example: \n\n```kotlin\nfun setDismissalId(dismissalId: String): WearableExtender\nfun getDismissalId(): String\n```\n\n\nTo sync a dismissal, use the\n[setDismissalId()](/reference/android/app/Notification.WearableExtender#setDismissalId(java.lang.String))\nmethod. For each notification, pass a globally unique ID as a string when you call the\n`setDismissalId()` method.\n\n\nWhen the notification dismisses, all other notifications with the same dismissal ID are\ndismissed on the watch and on the phone. To retrieve a dismissal ID, use\n`getDismissalId()`\n\n\nIn the following example, a globally unique ID is\nspecified for a new notification, so dismissals are synced: \n\n```kotlin\nval notification = NotificationCompat.Builder(context, channelId)\n // Set other fields ...\n .extend(\n NotificationCompat.WearableExtender()\n .setDismissalId(\"abc123\")\n )\n .build()\n```\n\n\n**Note:** Dismissal IDs work if a watch is paired to an Android phone, but not if a watch is\npaired to an iPhone.\n\nWhen notifications aren't bridged\n---------------------------------\n\n\nThe following types of notifications are not bridged:\n\n- Local-only notifications set using [Notification.Builder.setLocalOnly(boolean)](/reference/android/app/Notification.Builder#setLocalOnly(boolean)).\n- Ongoing notifications set using [Notification.Builder.setOngoing(boolean)](/reference/android/app/Notification.Builder#setOngoing(boolean)) or [Notification.FLAG_ONGOING_EVENT](/reference/android/app/Notification#FLAG_ONGOING_EVENT).\n- Non-clearable notifications set using [Notification.FLAG_NO_CLEAR](/reference/android/app/Notification#FLAG_NO_CLEAR).\n- Notifications where the counterpart wearable app has disabled notification bridging, as described previously.\n\nBest practices for bridged notifications\n----------------------------------------\n\n\nIt takes time to push or remove bridged notifications from a wearable\ndevice. As you design your notifications, make sure to avoid unexpected\nbehavior caused by this latency. The following guidelines help\nensure that your bridged notifications work with asynchronous notifications:\n\n- If you cancel a notification on the phone, it may take some time to cancel the corresponding notification on the watch. During this time, the user might send one of the pending intents on that notification. For this reason, continue to receive pending intents in your app from notifications it has canceled: when canceling notifications, keep those notifications' pending intent receivers valid.\n- Don't cancel and retrigger an entire stack of notifications at one time. Only modify or remove the notifications that have actually been modified. This avoids the latency on updating the wearable device and reduces your app's impact on battery life.\n\n### Design considerations\n\n\nWear OS notifications have their own design guidelines. For more information,\nreview the [Wear OS Design Guidelines](/training/wearables/design)."]]