Notifications & badges

Check authorization, request push and critical-alert permission, open settings, and set the app-icon badge.

Check notification status

Read the current notification authorization plus time-sensitive and critical-alert support. Safe to call even when those optional features are off — they report supported: false.

Property	Type	Description
`authorization`	`string`	`authorized`, `denied`, `notDetermined`, `provisional`, or `ephemeral`.
`timeSensitive`	`object`	`{ supported, setting?, channelId?, channelImportance?, channelEnabled? }`.
`critical`	`object`	`{ supported, authorization?, canRequest? }`.
`platform`	`string`	`ios` or `android`.

In a plain browser the call resolves ok: false with a code such as common/feature_disabled. Branch on !result.ok.

import { createBdkNative } from "@bdk/native/browser";

const bdk = createBdkNative();

const result = await bdk.notifications.status();

if (!result.ok) {
  return;
}

console.log(result.authorization, result.platform);
console.log(result.timeSensitive.supported, result.critical.supported);

Ask for push permission

Read the current push authorization, then request it. granted is true for both granted and provisional. When mode is manual, show your own explainer first, then call request().

Property	Type	Description
`status`	`string`	`granted`, `denied`, `notDetermined`, or `provisional`.
`granted`	`boolean`	True for `granted` and `provisional`.
`canPrompt`	`boolean`	Whether `request()` can still ask the user.
`canOpenSettings`	`boolean`	Whether the app can open notification settings.
`mode`	`string`	`automatic` or `manual`.

This feature can be switched off in a given app build. Check await bdk.capabilities.has("push.prompt") before showing the UI. When it is off, the call resolves ok: false with code: "common/feature_disabled". See Detect features.

if (!(await bdk.capabilities.has("push.prompt"))) {
  // Hide the prompt UI — this build does not include it.
}

const state = await bdk.push.status();

if (!state.ok) {
  return;
}

if (state.granted) {
  // Already allowed — includes provisional.
} else if (state.canPrompt) {
  const result = await bdk.push.request();
  if (!result.ok) return;
  console.log(result.status, result.granted);
}

Open notification settings

Send the user to the OS notification settings after a denial, or to change time-sensitive and channel options. notifications.openSettings() is the general deep-link; pass { channel: "urgent" } on Android to open the urgent channel. push.openSettings() is the same idea from the push-prompt namespace — no channel option.

const result = await bdk.notifications.openSettings();

if (!result.ok) return;
// result.opened === true — the OS settings screen was requested.

Request critical alerts

Ask for Apple's separate critical-alert permission. iOS only — it does not consume the ordinary push prompt. On Android the call resolves ok: false with code: "common/unsupported_platform".

This feature can be switched off in a given app build. Check await bdk.capabilities.has("notifications.critical") before showing the UI. When it is off, the call resolves ok: false with code: "common/feature_disabled". See Detect features.

if (!(await bdk.capabilities.has("notifications.critical"))) {
  // Hide the critical-alert UI.
}

const result = await bdk.notifications.requestCritical();

if (!result.ok) {
  // common/unsupported_platform on Android; common/feature_disabled when off.
  return;
}

console.log(result.granted, result.critical, result.authorization);

Set the app badge

Read, set, or clear the app-icon badge. iOS sets an exact count. Android set is unsupported (ok: false, code: "common/unsupported_platform"); get is an approximate count of active notifications (source: "active_notifications", approximate: true). clear works on both — on Android it reports how many cancellable notifications were removed.

Pass a finite non-negative integer to set. Check canSet() before offering a setter.

This feature can be switched off in a given app build. Check await bdk.capabilities.has("badge") before showing the UI. When it is off, the call resolves ok: false with code: "common/feature_disabled". See Detect features.

if (await bdk.badge.canSet()) {
  const result = await bdk.badge.set(5);
  if (!result.ok) return;
}

React to permission changes

Refresh status after the user answers a prompt or returns from Settings. permissions.changed fires when a tracked permission changes — not on the first snapshot — so subscribe before you call request or openSettings.

Property	Type	Description
`changed`	`string[]`	Type names that changed — includes `push` when notification authorization changes.
`previous`	`object`	Prior status per changed type.
`permissions`	`object`	Full current permission map.

bdk.on("permissions.changed", async ({ changed }) => {
  if (!changed.includes("push")) return;

  const push = await bdk.push.status();
  if (push.ok) console.log(push.status, push.granted);

  const notifications = await bdk.notifications.status();
  if (notifications.ok) console.log(notifications.authorization);
});

await bdk.push.request();
// or: await bdk.notifications.openSettings();