應用程式徽章 API 可讓已安裝的網頁應用程式在應用程式圖示上設定應用程式全域徽章。
什麼是 App Badging API?
應用程式徽章 API 可讓已安裝的網頁應用程式設定應用程式全域徽章,並顯示在與應用程式相關聯的作業系統特定位置 (例如書架或主畫面)。
使用徽章,您就能輕鬆地向使用者通知有需要注意的新活動,或是顯示少量資訊 (例如未讀數量)。
徽章比通知更友善,而且不會打斷使用者,因此可以更頻繁地更新。而且,由於不會中斷使用者,因此不需要使用者同意。
可能的應用方式
以下列舉可能使用這個 API 的應用程式:
- 即時通訊、電子郵件和社交應用程式,告知收到新訊息或顯示未讀項目的數量。
- 工作效率應用程式,用於指出長時間執行的背景工作 (例如算繪圖片或影片) 已完成。
- 遊戲,用於表示需要玩家採取行動 (例如在西洋棋中,當輪到玩家時)。
支援
App Badging API 適用於 Windows 和 macOS,適用於 Chrome 81 和 Edge 81 以上版本。我們正在開發 ChromeOS 支援功能,並會在日後的版本中推出。Android 不支援 Badging API。相反地,當安裝的網頁應用程式有未讀通知時,Android 會自動在應用程式圖示上顯示徽章,就像 Android 應用程式一樣。
立即試用
- 開啟 App Badging API 示範。
- 當系統提示時,按一下「Install」(安裝) 安裝應用程式,或使用 Chrome 選單安裝應用程式。
- 以已安裝的 PWA 形式開啟。請注意,它必須以已安裝的 PWA 形式執行 (在工作列或 Dock 中)。
- 按一下「Set」或「Clear」按鈕,設定或清除應用程式圖示中的徽章。您也可以為徽章值提供數字。
如何使用 App Badging API
如要使用應用程式徽章 API,您的網頁應用程式必須符合 Chrome 的安裝可行性標準,且使用者必須將應用程式新增至主畫面。
Badge API 包含 navigator
上的兩種方法:
setAppBadge(
number
)
:設定應用程式的徽章。如果提供值,請將標記設為提供的值,否則顯示純白點 (或適合平台的其他標記)。將number
設為0
,就等同於呼叫clearAppBadge()
。clearAppBadge()
:移除應用程式的徽章。
兩者都會傳回空白承諾,可用於錯誤處理。
您可以從目前的頁面或已註冊的 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 存在時呼叫 API,因為其他瀏覽器可能會在其他位置顯示徽章。如果方法奏效,那就放心去做;反之則不會。
透過服務工作者在背景設定及清除徽章
您也可以使用服務工作者,在背景設定應用程式徽章。您可以透過定期在背景同步處理、Push API,或兩者結合的方式進行這項操作。
定期在背景同步處理
定期背景同步處理可讓 Service Worker 定期輪詢伺服器 (可用於取得更新狀態),並呼叫 navigator.setAppBadge()
。
不過,呼叫同步作業的頻率並非完全可靠,而是由瀏覽器自行決定。
Web Push API
Push API 可讓伺服器將訊息傳送至服務工作者,即使沒有前景頁面執行,服務工作者也能執行 JavaScript 程式碼。因此,伺服器推送可透過呼叫 navigator.setAppBadge()
更新徽章。
不過,Chrome 等大多數瀏覽器都會在收到推播訊息時顯示通知。這對於某些用途 (例如在更新徽章時顯示通知) 來說沒問題,但如果不顯示通知,就無法巧妙地更新徽章。
此外,使用者必須授予網站通知權限,才能接收推送訊息。
兩者皆有
雖然不完美,但搭配運用 Push API 和定期背景同步處理,是不錯的解決方案。系統會透過 Push API 傳送高優先順序資訊,顯示通知並更新徽章。而較低優先順序的資訊則是透過更新徽章來提供,無論是在網頁開啟時,或是透過定期的背景同步處理作業。
意見回饋
Chrome 團隊希望瞭解你使用 App Badging API 的體驗。
請說明 API 設計
API 中是否有任何功能無法正常運作?或者,您是否缺少實作想法所需的方法或屬性?您對安全性模型有任何疑問或意見嗎?
- 在 Badging API GitHub 存放區中提出規格問題,或在現有問題中加入您的想法。
回報實作問題
你是否發現 Chrome 實作項目有錯誤?還是實作方式與規格不同?
- 請前往 https://new.crbug.com 提交錯誤。請務必盡可能提供詳細資訊、重現問題的簡單操作說明,並將「元件」設為
UI>Browser>WebAppInstalls
。Glitch 非常適合用於分享快速簡單的再現內容。
顯示 API 支援
想要在網站上使用 App Badging API 嗎?您的公開支援服務可協助 Chrome 團隊優先開發功能,並讓其他瀏覽器廠商瞭解支援這些功能的重要性。
- 使用主題標記
#BadgingAPI
發送推文給 @ChromiumDev,告訴我們你在何處使用這項功能,以及使用方式。
實用連結
- 公開說明
- 規格草稿
- 徽章 API 示範 | 徽章 API 示範來源
- 追蹤錯誤
- ChromeStatus.com 項目
- Blink 元件:
UI>Browser>WebAppInstalls
主頁相片來源:Prateek Katyal 在 Unsplash 網站上提供