應用程式圖示徽章

應用程式 Badging API 可讓已安裝的網頁應用程式在應用程式圖示上設定全應用程式的徽章。

Pete LePage

什麼是 App Badging API？

App Badging API 可讓已安裝的網頁應用程式設定通用的徽章。 並且會顯示於與應用程式相關的作業系統 (例如檔案櫃或主畫面)。

徽章可讓你輕鬆以輕微的方式告知使用者有新活動 可能須留意的特性 例如未讀取的計數

徽章比通知更易於使用，且可以更新 且不會幹擾使用者，因此頻率也更高此外， 因為系統不會中斷使用者，也不需要使用者授予權限。

可能的應用方式

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

• 即時通訊、電子郵件和社交應用程式：傳送新訊息或 顯示未讀取項目的數量。
• 效率提升應用程式，表示需要長時間執行的背景工作 (例如 算繪圖片或影片) 已完成。
• 遊戲：指出玩家必須執行動作 (例如「西洋棋」 即玩家輪到的結果)。

支援

App Badging API 適用於 Windows 和 macOS，適用於 Chrome 81 和 Edge 81 以上版本。 ChromeOS 的支援服務仍在開發階段，將於日後開放使用 版本。Android 不支援 Badging API。 Android 會自動在已安裝的網頁應用程式圖示上顯示徽章 就和 Android 應用程式一樣

立即試用

1. 開啟 應用程式徽章 API 示範
2. 當系統提示時，按一下「安裝」安裝應用程式，或使用 Chrome 安裝應用程式
3. 以已安裝的 PWA 的形式開啟應用程式。請注意，它必須以已安裝的 PWA 的形式執行 (位於工作列或 Dock)。
4. 按一下「設定」或「清除」按鈕，設定或清除應用程式中的徽章 圖示。您也可以為徽章值提供數字，

如何使用 App Badging API

如要使用 App Badging 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 (如有)，因為其他瀏覽器可能會在其他位置顯示徽章。 如果成功，就表示可行。反之則不會。

由服務工作人員在背景設定及清除標記

您也可以使用 Service Worker 在背景設定應用程式徽章。採取以下任一做法： 透過定期背景同步處理、Push API 或兩者並用

定期在背景同步處理

定期背景同步處理可讓 Service Worker 定期輪詢伺服器，藉此取得更新後的狀態 並呼叫 navigator.setAppBadge()。

但是，執行同步作業的頻率並不穩定 並由瀏覽器自行斟酌呼叫。

網路推送 API

Push API 可讓伺服器傳送訊息給服務工作站。 ，即使沒有執行前景頁面，也能執行 JavaScript 程式碼。因此， 伺服器推送可以呼叫 navigator.setAppBadge() 來更新標記。

不過，多數瀏覽器 (包括 Chrome) 規定 。這對某些用途而言 案例 (例如在更新時顯示通知 但無法微調徽章 顯示通知

此外，使用者必須授予網站通知權限，才能 接收推送訊息

結合

不盡完美，同時使用 Push API 和定期背景同步處理 提供了良好的解決方案高優先順序資訊會透過推送傳送 API，顯示通知並更新徽章。且優先順序較低 任何一種資訊都會透過更新徽章的方式傳遞。 或是定期背景同步

意見回饋

Chrome 團隊希望瞭解您使用 App Badging API 的體驗，

請與我們分享 API 設計

是否有 API 未正常運作？或是 沒有你想實現創意的方法或屬性嗎？ 您對安全性模型有任何疑問或意見嗎？

• 在 Badging API GitHub 存放區上提交規格問題，或新增 對現有議題的看法

回報導入問題

您發現 Chrome 實作錯誤嗎？另一種是實作 該怎麼辦？

• 前往 https://new.crbug.com 回報錯誤。請務必盡量附上 可以提供重現重現的簡單操作說明，並將「Components」(元件) 設為 UI>Browser>WebAppInstalls。Glitch 適用於以下情境： 分享快速簡單的重製版本

顯示對 API 的支援

想要在網站上使用 App Badging API 嗎？你的公開支援讓 優先考慮功能，並向其他瀏覽器供應商說明其重要性 就必須支持他們

• 使用主題標記將推文傳送至 @ChromiumDev #BadgingAPI敬上 ，並說明你使用這項服務的位置和方式。

實用連結

• 公開說明
• 規格草稿
• 徽章 API 示範 |徽章 API 示範來源
• 追蹤錯誤
• ChromeStatus.com 項目
• 閃爍元件：UI>Browser>WebAppInstalls

主頁相片提供者： Prateek Katyal 已啟用 不通膨