在應用圖示上顯示徽章

對徽章的支援

應用徽章僅在 PWA 安裝到其宿主作業系統後才受支援。徽章會顯示在應用圖示上，而應用圖示只有在應用安裝後才會存在。

桌面支援

在桌面作業系統上，徽章僅在 Windows 和 macOS 上受支援，並且僅當 PWA 是從 Chrome 或 Edge 安裝時才支援。雖然徽章 API 在 Linux 上的基於 Chromium 的瀏覽器中受支援，但在該作業系統上不顯示徽章。

桌面上的 Safari 和 Firefox 不支援徽章 API，也不支援安裝 PWA。

移動支援

從 iPadOS 16.4 開始，Safari 在 iOS 和 iPadOS 上支援徽章。徽章 API 在 Android 上執行的基於 Chromium 的瀏覽器中不受支援。取而代之的是，當有未讀通知時，Android 會像對待 Android 應用一樣，自動在 PWA 的應用圖示上顯示徽章。

徽章最佳實踐

在學習如何使用徽章之前，請考慮這些最佳實踐，以確保您的應用以最有效和最有用的方式為您的使用者使用徽章。

檢查支援情況

為確保使用者瀏覽器和作業系統 支援 徽章 API，防止 JavaScript 錯誤，請在使用 API 前檢查支援情況。

if (navigator.setAppBadge) {
  // The API is supported, use it.
} else {
  // The API is not supported, don't use it.
}

不要僅依賴徽章來通知使用者新內容可用。支援徽章 API 的瀏覽器可能安裝在不支援顯示徽章的作業系統上。例如，雖然 Chrome 支援徽章 API，但在 Linux 上安裝的應用圖示上不會顯示徽章。

請求 iOS 和/或 iPadOS 的通知許可權

雖然 iOS 和 iPadOS 支援通知徽章，但在授予應用程式通知許可權之前，徽章不會出現。要請求通知許可權，請呼叫 Notification.requestPermission() 方法。

Notification.requestPermission().then((result) => {
  console.log(result);
});

您還可以選擇使用 許可權 API 檢查使用者是否之前已授予通知許可權。

謹慎使用徽章

與通知一樣，徽章可以在謹慎使用時成為重新吸引使用者使用您的應用的有效方式。請確保僅使用徽章來指示對您的使用者很重要的新內容。

即時更新徽章

確保即時更新您的應用程式徽章。這意味著將徽章計數更新為反映使用者實際還有多少新專案可供消費，並在沒有新專案時清除應用徽章。

例如，如果電子郵件客戶端應用在後臺收到新郵件，它應該更新其徽章以顯示收件箱中未讀郵件的正確數量，可能還會過濾掉其他資料夾（如垃圾郵件資料夾）中的郵件。可以使用服務工作執行緒中的 navigator.setAppBadge() 方法 在後臺更新徽章。

一旦使用者啟動應用程式並開始閱讀郵件，電子郵件客戶端應用就應該透過呼叫帶有新未讀郵件計數的新 navigator.setAppBadge()，或在沒有未讀郵件時呼叫 navigator.clearAppBadge() 來相應地更新其徽章。

在應用中突出顯示新內容

當您的應用收到新內容並在應用圖示上新增徽章時，請確保在使用者啟動應用時突出顯示該新內容。

例如，如果電子郵件客戶端應用在應用圖示徽章上顯示未讀郵件數量，那麼當應用開啟時，這些郵件應該加粗或以某種方式突出顯示。

顯示和更新徽章

要顯示 PWA 應用圖示上的徽章以顯示未讀郵件數量，請使用 Navigator.setAppBadge() 方法。

// Check for support first.
if (navigator.setAppBadge) {
  // Display the number of unread messages.
  navigator.setAppBadge(numberOfUnreadMessages);
}

您也可以透過省略計數引數或將其設定為 0 來使用相同的方法顯示一個空的徽章。

// Check for support first.
if (navigator.setAppBadge) {
  // Just display the badge, with no number in it.
  navigator.setAppBadge();
}

要刪除應用圖示上的徽章，請使用 Navigator.clearAppBadge() 方法。

// Check for support first.
if (navigator.clearAppBadge) {
  // Remove the badge on the app icon.
  navigator.clearAppBadge();
}

在後臺更新徽章

當用戶不使用您的應用時，徽章可以幫助他們重新參與到您的應用中。這意味著您的應用必須能夠在未執行時更新其徽章。

PWA 可以使用以下機制在後臺更新並顯示、更新或隱藏其徽章：

推送 API

PWA 可以使用此 API 在應用未執行時接收來自伺服器的訊息。大多數瀏覽器在收到推送訊息時都需要顯示通知。這對於某些用例（例如，在更新徽章時顯示通知）是可以的，但使得在不顯示通知的情況下微妙地更新徽章成為不可能。此外，使用者必須授予您的網站通知許可權才能接收推送訊息。有關更多資訊，請參閱 ServiceWorkerRegistration: showNotification() 方法。

Background Synchronization API

PWA 可以使用此 API 在檢測到穩定的網路連線時在後臺執行程式碼。

Web Periodic Background Synchronization API

PWA 可以使用此 API 在預定的時間間隔內執行程式碼。

這是一個服務工作執行緒程式碼示例，展示瞭如何監聽伺服器的推送訊息並更新應用徽章以反映未讀郵件數量。

// Listen to "push" events in the service worker.
self.addEventListener("push", (event) => {
  // Extract the unread count from the push message data.
  const message = event.data.json();
  const unreadCount = message.unreadCount;

  // Set or clear the badge.
  if (navigator.setAppBadge) {
    if (unreadCount && unreadCount > 0) {
      navigator.setAppBadge(unreadCount);
    } else {
      navigator.clearAppBadge();
    }
  }
  // It's obligatory to show the notification to the user.
  self.registration.showNotification(`${unreadCount} unread messages`);
});

另見

• 如何建立應用徽章
• 應用圖示的徽章
• 使用徽章、通知和推送訊息重新吸引使用者
• 編碼實驗：構建一個推送通知伺服器