SDK API

Constructor

import { Nudgr } from "nudgr";

const nudgr = new Nudgr({
  apiKey: "nk_...",
  apiBase: "https://api.nudgr.dev",
  swPath: "/nudgr-sw.mjs",
  swScope: "/",
  foreground: {
    timeoutMs: 1200,
    async onPush(payload) {
      return { showNotification: false };
    },
  },
});

Create one shared Nudgr instance per page or app shell. Do not create a new instance on every render.

Options

Option	Type	Required	Default
apiKey	string	yes	none
apiBase	string	no	https://api.nudgr.dev
swPath	string	no	/nudgr-sw.mjs
swScope	string	no	/
foreground	object	no	disabled

apiKey

Your project API key. This is the nk_... credential used by the browser SDK when it registers subscriptions and reports unsubscribe events.

apiBase

The Nudgr API origin the SDK should talk to. You normally leave this at the production default:

apiBase: "https://api.nudgr.dev";

Override this only when you are testing against a local or staging API.

swPath

The public URL where your service worker file is served from your site.

swPath: "/nudgr-sw.mjs";

This must match a real browser-accessible URL on your origin.

swScope

The URL scope the service worker controls.

swScope: "/";

Use a narrower scope such as /push/ when you want to isolate Nudgr from other service workers or PWA behavior.

foreground

Use foreground when your app is open and you want the page to decide whether a push should still become a system notification.

const nudgr = new Nudgr({
  apiKey: "nk_...",
  foreground: {
    timeoutMs: 1200,
    async onPush(payload) {
      showToast(payload.title);
      return { showNotification: false };
    },
  },
});

foreground fields:

Field	Type	Required	Default
timeoutMs	number	no	1200
onPush	(payload) => boolean | { showNotification?: boolean } | Promise<...>	no	none

Behavior:

• if there is no visible page, Nudgr still shows a system notification
• if there is a visible page, Nudgr asks foreground.onPush
• if onPush returns false or { showNotification: false }, the system notification is suppressed
• if onPush returns true, { showNotification: true }, throws, or times out, Nudgr shows the system notification

This keeps the default behavior safe: if you do nothing, push notifications still work exactly as before.

Methods

await nudgr.subscribe({ tags })

Requests notification permission, registers the service worker, fetches the VAPID public key, creates a browser push subscription, and registers that subscription with Nudgr.

Optional subscribe fields:

• tags: string array attached to the subscription, for example ["vip", "zh-CN"]

Returns:

type NudgrSubscription = {
  id: string;
  endpoint: string;
  created_at: string;
  tags?: string[];
};

Example:

await nudgr.subscribe({
  tags: ["vip", "zh-CN"],
});

await nudgr.unsubscribe()

Deletes the current subscription from Nudgr by endpoint, then unsubscribes the current browser from push notifications.

The browser unsubscribe happens first. If Nudgr cannot remove the remote subscription immediately, the current browser still stops receiving notifications.

Returns:

boolean;

await nudgr.isSubscribed()

Checks whether the current browser already has an active push subscription.

Returns:

boolean;

Nudgr.isSupported()

Checks whether the current browser supports the APIs required for push notifications.

Nudgr.getPermission()

Returns the current notification permission:

"default" | "granted" | "denied";

Errors

The SDK throws when:

• apiKey is missing
• push is not supported in the current browser
• notification permission is denied
• the Nudgr API returns a non-2xx response