standardized-app-badge

Cross-browser wrapper for Navigator Badge API

Wraps the Badging API into a cross-browser set of utilities for easier feature detection and more consistent behaviour between browsers.

Features

• TypeScript support
• Under 560 bytes GZipped
• setAppBadge and clearAppBadge throw errors if webapp is not installed or running in an insecure context
• Safely detect and fallback on unsupported browsers using isAppBadgeSupported method

Installation

pnpm

pnpm add standardized-app-badge

Yarn

yarn add standardized-app-badge

npm

npm install standardized-app-badge

Usage

import { 
  setAppBadge,
  clearAppBadge, 
  isAppBadgeSupported,
  isAppBadgeAllowed,
  requestAppBadgePermission
} from 'standardized-app-badge'

const button = document.createElement('button')
button.innerHTML = "Set app badge and clear after 10s seconds"
if (isAppBadgeSupported()) {
  button.onclick = () => {
    const request = async () => {
      const canSetAppBadge = await requestAppBadgePermission()
      if (canSetAppBadge) {
        setTimeout(() => {
          const set = async () => {
            try {
              await setAppBadge(1)
              console.log('Set pending badge notification on dock or taskbar')
            } catch (e) {
              console.error('Could not set badge notification', e)
            }
          }
          void set()
        }, 1000)
        setTimeout(() => void clearAppBadge(), [10_000])
      } else {
        console.warn('Could not get badge notification permission')
      }
    }
    void request()
  }
} else {
  button.onclick = () => {
    console.warn('Unsupported browser')
  }
}
document.body.append(button)

Methods

setAppBadge(contents?: number) => Promise<void> // throws DOMException

Sets the app badge icon on the associated installed app either on the dock or taskbar. If no value is passed, only a indicator dot will be shown. Otherwise the notification count is displayed.

In-order for this method to work:

• The webpage must be installed as an app.
• Running over a secure-context (HTTPS).
• Granted notification permission with requestAppBadgePermission() (for Safari iOS) or enabled in the app settings (for MacOS Safari).

This method will resolve if set successfully or throw an error if:

• The webpage is not installed as an app.
• The webpage is running in an insecure-context (HTTP).
• The browser does not support API.
• Permission was not granted (Safari)

clearAppBadge() => Promise<void> // throws DOMException

Clears the app badge icon on the associated installed app either on the dock or taskbar.

In-order for this method to work:

• The webpage must be installed as an app.
• Running over a secure-context (HTTPS).
• Granted notification permission with requestAppBadgePermission() (for Safari iOS) or enabled in the app settings (for MacOS Safari).

This method will resolve if set successfully or throw an error if:

• The webpage is not installed as an app.
• The webpage is running in an insecure-context (HTTP).
• The browser does not support API.
• Permission was not granted (Safari).

isAppBadgeSupported() => boolean

Queries if the app badge is supported.

This method will check that:

• The browser supports the badge API.
• The webpage is running over a secure-context (HTTPS).
• The webpage is running & installed as an app.

However this method does not check if the permission to display the badge was granted (Safari only). In-order to do this call isAppBadgeAllowed().

isAppBadgeAllowed() => "denied" | "granted" | "unknown"

Queries if the app badge has been granted permission.

• If the app badge is not supported, 'denied' is returned.

• If the webpage Chromium based, no permission is needed and 'granted' is returned.

• Otherwise the browser requires permission and 'unknown' is returned.

  In this case requestAppBadgePermission() should be called. Alternatively navigator.permissions.query({ name: 'notifications' }) can be called if you only want to query the status without prompting but requestAppBadgePermission() does this prior to prompting.

requestAppBadgePermission() => Promise<boolean>

Queries if the app badge needs permission or has been granted permission.

If permission is needed, it will prompt for the user to provide the permission.

• false is returned if the app badge is not supported or the method could not obtain permission. This can happen if the user denies the prompt or has it blocked.
• true is returned if the app badge does not require any permission or if it succesfully obtained permission.