App Badging API 允許已安裝的網頁應用程式在應用程式圖示上設定全應用程式標記。
什麼是 App Badging API?
透過 App Badging API,已安裝的網頁應用程式可以設定全應用程式標記,這個標記會顯示在與應用程式相關聯的作業系統專屬位置 (例如檔案櫃或主畫面)。
標記有助於輕鬆向使用者發出小幅通知,告知他們有新的活動可能需要關注,或是指出少量資訊,例如未讀取的數量。
徽章通常比通知更易於使用,且由於不會幹擾使用者,因此更新的頻率也更高。此外,由於使用者不會中斷使用者,因此不需要使用者授權。
可能的用途
以下列舉可能會使用這個 API 的應用程式:
- 即時通訊、電子郵件和社交應用程式,可指出新訊息已送達,或顯示未讀項目的數量。
- 效率提升應用程式,可表明長時間執行的背景工作 (例如轉譯圖片或影片) 已完成。
- 遊戲,藉此表明玩家需要執行一些動作 (例如,在小西 (Chess) 中,就是玩家回合)。
支援
App Badging API 適用於 Windows 和 macOS,適用於 Chrome 81 以上版本、Edge 81 以上版本。我們正在開發 ChromeOS 相關支援,預計於日後推出的版本中提供。在 Android 中,不支援 Badging API。相反地,如果有未讀取的通知,Android 會自動在已安裝網頁應用程式的應用程式圖示中顯示標記,就像 Android 應用程式一樣。
立即試用
- 開啟應用程式徽章 API 示範。
- 出現提示時,按一下「Install」安裝應用程式,或使用 Chrome 選單來安裝應用程式。
- 在已安裝的 PWA 中開啟此應用程式。請注意,程式庫必須以已安裝的 PWA 的形式執行 (在工作列或 Dock 中)。
- 按一下「設定」或「清除」按鈕,即可從應用程式圖示設定或清除徽章。你也可以提供徽章值的數字。
如何使用 App Badging API
如要使用 App Badging API,網頁應用程式必須符合 Chrome 的安裝條件,且使用者必須將該 API 新增至主畫面。
Badge API 包含 navigator
上的兩種方法:
setAppBadge(
number
)
:設定應用程式的徽章。如果提供值,請將徽章設為提供的值,否則顯示純白圓點 (或適合平台的其他標記)。將number
設為0
與呼叫clearAppBadge()
相同。clearAppBadge()
:移除應用程式徽章。
這兩種傳回空白的承諾都可用於處理錯誤。
徽章可從目前的頁面,或從已註冊的 Service Worker 設定。如要設定或清除標記 (在前景頁面或 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,因為其他瀏覽器可能會顯示徽章。如果能成功,就沒問題了。否則就不會發生。
由服務工作人員在背景設定及清除識別證
您也可以使用 Service Worker,在背景設定應用程式徽章。方法是定期背景同步處理、Push API,或兩者併用。
定期在背景同步處理
定期背景同步處理可讓服務工作站定期輪詢伺服器,可用來取得最新狀態,然後呼叫 navigator.setAppBadge()
。
不過,呼叫同步處理的頻率並不完全可靠,瀏覽器可自行斟酌如何呼叫。
網路推播 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
將 Tweet 訊息傳送至 @ChromiumDev,並告訴我們您的使用地點和方式。
實用連結
- 公開說明
- 規格草稿
- Badging API 示範 | Badging API 示範來源
- 追蹤錯誤
- ChromeStatus.com 項目
- 閃爍元件:
UI>Browser>WebAppInstalls
Prateek Katyal 在 Unsplash 提供的主頁相片