借助 App Badging API,已安装的 Web 应用可以在应用图标上设置应用级标记。
什么是 App Badging API?
借助 App Badging API,已安装的 Web 应用可以设置应用级标记,该标记会显示在与应用关联的操作系统专用位置(例如搁架或主屏幕)。
借助标记,您可以轻松以不易察觉的方式通知用户有可能需要他们注意的新 activity,或指明少量信息(例如未读计数)。
标记往往比通知更人性化,并且能够以更高的频率更新,因为它们不会干扰用户。由于这些通知不会干扰用户,因此无需用户授权。
可能的用例
可能使用此 API 的应用示例包括:
- 聊天、电子邮件和社交应用,用于指示有新消息到达或显示未读内容的数量。
- 效率应用,用于指示长时间运行的后台任务(例如渲染图片或视频)已完成。
- 游戏,用于指示需要玩家执行操作(例如,在国际象棋中,当轮到玩家时)。
支持
App Badging API 适用于 Windows 和 macOS 中的 Chrome 81 和 Edge 81 或更高版本。对 ChromeOS 的支持正在开发中,将在未来的版本中提供。在 Android 上,不支持 Badging API。相反,当有未读通知时,Android 会自动在已安装 Web 应用的应用图标上显示标志,就像 Android 应用一样。
试试看
- 打开 App Badging API 演示。
- 出现提示时,点击安装安装该应用,或使用 Chrome 菜单安装该应用。
- 以已安装的 PWA 的形式打开该应用。请注意,该应用必须作为已安装的 PWA 运行(在任务栏或基座中)。
- 点击设置或清除按钮,设置或清除应用图标中的标志。您还可以为徽章值提供一个数字。
如何使用 App Badging API
如需使用 App Badging API,您的网络应用需要符合 Chrome 的安装性条件,并且用户必须将其添加到主屏幕。
Badge API 包含 navigator
上的两个方法:
setAppBadge(
number
)
:设置应用的徽章。如果提供了值,则将标志设置为提供的值,否则显示纯白点(或适用于平台的其他标志)。将number
设置为0
与调用clearAppBadge()
相同。clearAppBadge()
:移除应用的标记。
这两者都会返回空 promise,您可以将其用于错误处理。
徽章可以从当前页面或已注册的服务工作器设置。如需设置或清除标志(在前台页面或 Service Worker 中),请调用:
// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
//Do something with the error.
});
// Clear the badge
navigator.clearAppBadge().catch((error) => {
// Do something with the error.
});
在某些情况下,操作系统可能不允许准确显示徽章。在这种情况下,浏览器会尝试为该设备提供最佳呈现效果。例如,由于 Android 不支持 Badging API,因此 Android 始终只会显示一个圆点,而不是数字值。
请勿对用户代理显示徽章的方式做出任何假设。某些用户代理可能会将“4000”等数字重写为“99+”。如果您自行饱和徽章(例如将其设置为“99”),则“+”号不会显示。无论实际数字如何,只需调用 setAppBadge(unreadCount)
,让用户代理相应地处理显示即可。
虽然 Chrome 中的 App Badging API 需要已安装的应用,但您不应根据安装状态调用 Badging API。只需在存在时调用该 API,因为其他浏览器可能会在其他位置显示徽章。如果能行得通,就行。如果没有,则不会显示。
通过 Service Worker 在后台设置和清除标记
您还可以使用服务工件在后台设置应用标记。您可以通过定期后台同步和/或 Push API 来实现此目的。
定期后台同步
定期后台同步允许 Service Worker 定期轮询服务器(可用于获取更新状态)并调用 navigator.setAppBadge()
。
不过,调用同步的频率并不十分可靠,该频率由浏览器自行决定。
Web 推送 API
借助 Push API,服务器可以向服务工作器发送消息,即使没有任何前台页面在运行,服务工作器也可以运行 JavaScript 代码。因此,服务器推送可以通过调用 navigator.setAppBadge()
来更新徽章。
不过,大多数浏览器(包括 Chrome)都要求在收到推送消息时显示通知。这对于某些用例(例如在更新徽章时显示通知)来说是可以接受的,但无法在不显示通知的情况下巧妙地更新徽章。
此外,用户必须向您的网站授予通知权限,才能接收推送消息。
结合使用这两者
虽然不完美,但将 Push API 和定期后台同步结合使用是一个不错的解决方案。系统会通过 Push API 传送高优先级信息,以显示通知并更新标记。系统会在网页打开时或通过定期后台同步更新标记,以传达优先级较低的信息。
反馈
Chrome 团队希望了解您使用 App Badging API 的体验。
请向我们说明 API 设计
API 中是否有的代码无法按预期运行?或者,您是否缺少实现自己的想法所需的方法或属性? 您对安全模型有疑问或意见吗?
- 在 Badging API GitHub 代码库中提交规范问题,或将您的想法添加到现有问题中。
报告实现方面的问题
您是否发现了 Chrome 实现中的 bug?还是实现与规范不同?
- 请前往 https://new.crbug.com 提交 bug。请务必提供尽可能详细的信息、简单的重现说明,并将组件设置为
UI>Browser>WebAppInstalls
。故障非常适合分享快速轻松的再现内容。
显示对该 API 的支持
计划在您的网站上使用 App Badging API?您的公开支持有助于 Chrome 团队确定功能的优先级,并向其他浏览器供应商表明支持这些功能非常重要。
- 使用
#BadgingAPI
标签向 @ChromiumDev 发送推文,告诉我们您在哪里以及如何使用该工具。
实用链接
- 公开铺垫消息
- 规范草稿
- Badging API 演示 | Badging API 演示源代码
- 跟踪 bug
- ChromeStatus.com 条目
- 闪烁组件:
UI>Browser>WebAppInstalls
主打照片,由 Prateek Katyal 在 Un 划过上发布