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 "@thebdk/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. mode is the app's prompt timing: automatic asks when the app opens; manual never asks until you call request(), so show your own explainer first. Read it from status() — it can change without an app update. Call request() after await bdk.ready(), from a user tap.

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`. The app's prompt timing.

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 — push is off in this app.
}

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();