應用程式圖示徽章

App Badging API 允許已安裝的網頁應用程式在應用程式圖示上設定全應用程式標記。

什麼是 App Badging API?

含有八則通知的 Twitter 範例,以及另一個顯示旗幟類型徽章的應用程式。
含有八則通知的 Twitter 範例,以及另一個顯示旗幟類型徽章的應用程式。

透過 App Badging API,已安裝的網頁應用程式可以設定全應用程式標記,這個標記會顯示在與應用程式相關聯的作業系統專屬位置 (例如檔案櫃或主畫面)。

標記有助於輕鬆向使用者發出小幅通知,告知他們有新的活動可能需要關注,或是指出少量資訊,例如未讀取的數量。

徽章通常比通知更易於使用,且由於不會幹擾使用者,因此更新的頻率也更高。此外,由於使用者不會中斷使用者,因此不需要使用者授權。

可能的用途

以下列舉可能會使用這個 API 的應用程式:

  • 即時通訊、電子郵件和社交應用程式,可指出新訊息已送達,或顯示未讀項目的數量。
  • 效率提升應用程式,可表明長時間執行的背景工作 (例如轉譯圖片或影片) 已完成。
  • 遊戲,藉此表明玩家需要執行一些動作 (例如,在小西 (Chess) 中,就是玩家回合)。

支援

App Badging API 適用於 Windows 和 macOS,適用於 Chrome 81 以上版本、Edge 81 以上版本。我們正在開發 ChromeOS 相關支援,預計於日後推出的版本中提供。在 Android 中,不支援 Badging API。相反地,如果有未讀取的通知,Android 會自動在已安裝網頁應用程式的應用程式圖示中顯示標記,就像 Android 應用程式一樣。

立即試用

  1. 開啟應用程式徽章 API 示範
  2. 出現提示時,按一下「Install」安裝應用程式,或使用 Chrome 選單來安裝應用程式。
  3. 在已安裝的 PWA 中開啟此應用程式。請注意,程式庫必須以已安裝的 PWA 的形式執行 (在工作列或 Dock 中)。
  4. 按一下「設定」或「清除」按鈕,即可從應用程式圖示設定或清除徽章。你也可以提供徽章值的數字。

如何使用 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 中是否有不如預期運作的功能?或是您需要實作提案的方法或屬性嗎?您對於安全性模型有任何疑問或意見嗎?

回報導入問題

您在執行 Chrome 時發現錯誤了嗎?還是實作與規格不同?

  • 前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊、重現簡易操作說明,並將「元件」設為 UI>Browser>WebAppInstallsGlitch 適合用來分享快速又簡單的重製內容。

展現對 API 的支援

打算在網站上使用 App Badging API 嗎?在公開支援的協助下,Chrome 團隊可決定各項功能的優先順序,並讓其他瀏覽器廠商知道對這些功能的支援程度有多重要。

  • 請使用主題標記 #BadgingAPI 將 Tweet 訊息傳送至 @ChromiumDev,並告訴我們您的使用地點和方式。

實用連結

Prateek KatyalUnsplash 提供的主頁相片