@capawesome/capacitor-badge¶

Capacitor plugin to access and update the badge number of the app icon.

Installation¶

npm install @capawesome/capacitor-badge
npx cap sync

Android¶

Variables¶

This plugin will use the following project variables (defined in your app’s variables.gradle file):

$shortcutBadgerVersion version of me.leolin:ShortcutBadger (default: 1.1.22)

iOS¶

Privacy manifest¶

Add the NSPrivacyAccessedAPICategoryUserDefaults dictionary key to your Privacy Manifest (usually ios/App/PrivacyInfo.xcprivacy):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

Configuration¶

These configuration values are available:

Prop	Type	Description	Default
`persist`	`boolean`	Configure whether the plugin should restore the counter after a reboot or app restart. Only available on Android and iOS.	`true`
`autoClear`	`boolean`	Configure whether the plugin should reset the counter after resuming the application. Only available on Android and iOS.	`false`

Examples¶

In capacitor.config.json:

{
  "plugins": {
    "Badge": {
      "persist": true,
      "autoClear": false
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-badge" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Badge: {
      persist: true,
      autoClear: false,
    },
  },
};

export default config;

Demo¶

A working example can be found here: robingenz/capacitor-plugin-demo

Usage¶

import { Badge } from '@capawesome/capacitor-badge';

const get = async () => {
  const result = await Badge.get();
  return result.count;
};

const set = async (count: number) => {
  await Badge.set({ count });
};

const increase = async () => {
  await Badge.increase();
};

const decrease = async () => {
  await Badge.decrease();
};

const clear = async () => {
  await Badge.clear();
};

const isSupported = async () => {
  const result = await Badge.isSupported();
  return result.isSupported;
};

const checkPermissions = async () => {
  const result = await Badge.checkPermissions();
};

const requestPermissions = async () => {
  const result = await Badge.requestPermissions();
};

get()¶

get() => Promise<GetBadgeResult>

Get the badge count. The badge count won't be lost after a reboot or app restart.

Default: 0.

Returns: Promise<GetBadgeResult>

set(...)¶

set(options: SetBadgeOptions) => Promise<void>

Set the badge count.

Param	Type
`options`	`SetBadgeOptions`

increase()¶

increase() => Promise<void>

Increase the badge count.

decrease()¶

decrease() => Promise<void>

Decrease the badge count.

clear()¶

clear() => Promise<void>

Clear the badge count.

isSupported()¶

isSupported() => Promise<IsSupportedResult>

Check if the badge count is supported.

Returns: Promise<IsSupportedResult>

checkPermissions()¶

checkPermissions() => Promise<PermissionStatus>

Check permission to display badge.

Returns: Promise<PermissionStatus>

requestPermissions()¶

requestPermissions() => Promise<PermissionStatus>

Request permission to display badge.

Returns: Promise<PermissionStatus>

Interfaces¶

GetBadgeResult¶

Prop	Type
`count`	`number`

SetBadgeOptions¶

Prop	Type
`count`	`number`

IsSupportedResult¶

Prop	Type
`isSupported`	`boolean`

PermissionStatus¶

Prop	Type	Description
`display`	`PermissionState`	Permission state of displaying the badge.

Type Aliases¶

PermissionState¶

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Quirks¶

On Android not all launchers support badges. This plugin uses ShortcutBadger. All supported launchers are listed there.

On Web, the app must run as an installed PWA (in the taskbar or dock).

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

Credits¶

This plugin is based on the Capacitor Badge plugin. Thanks to everyone who contributed to the project!