Quick Start

1. Install the SDK

npm install nudgr

Need setup details? See Installation.

2. Expose a service worker file on your site

The browser must be able to load a service worker from your own origin.

For the quick start, assume you expose one at:

/nudgr-sw.mjs

If you do not already have a service worker, the practical way to do this today is to copy:

node_modules/nudgr/dist/nudgr-sw.mjs

to a URL your site serves, such as /nudgr-sw.mjs.

If you already have a service worker or want a dedicated sub-path such as /push/nudgr-sw.mjs, see Service Worker.

3. Subscribe users

import { Nudgr } from "nudgr";

const nudgr = new Nudgr({
  apiKey: "nk_...",
  swPath: "/nudgr-sw.mjs",
  swScope: "/",
});

await nudgr.subscribe();

More options and methods: SDK API. The key mental model is swPath + swScope, not any specific framework directory name.

Optional: handle pushes differently while the app is open

If your app is visible and you want to keep the message in-app instead of always showing a browser notification, add foreground.onPush:

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

This only affects visible foreground pages. If no page is visible, Nudgr still shows the system notification.

4. Send a notification

curl -X POST https://api.nudgr.dev/v1/notifications/send \
  -H "Authorization: Bearer nk_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello!", "body": "Your first push notification"}'

More request fields: see the broader docs in your existing site or API docs. Exact endpoints and response shapes: API Reference.

Notes

• notification.sent means the push service accepted the request.
• It does not guarantee the user saw the notification.
• To track clicks, enable project webhooks in the dashboard.
• Project settings and credential locations are managed in the dashboard.