@flowpush/web-sdk

FlowPush browser SDK for Web Push notifications.

This package helps you:

• Register a service worker for push notifications
• Request notification permission
• Subscribe/unsubscribe browser devices
• Identify logged-in users and attach attributes

Install

pnpm add @flowpush/web-sdk

Requirements

• HTTPS origin in production (required by Push API and Service Workers)
• A FlowPush app with platform WEB
• VAPID keys configured on that app
• A public service worker file served by your app

Service Worker Setup

The SDK package builds a worker file at dist/sw.js.

Copy that file into your app public folder as sw.js (or serve it at a custom path):

cp node_modules/@flowpush/web-sdk/dist/sw.js public/sw.js

If you serve it from a different URL, pass serviceWorkerPath when creating the SDK client.

Quick Start

import { FlowPush } from "@flowpush/web-sdk"

const flowpush = new FlowPush({
  appKey: "your-app-key",
  apiUrl: "https://your-api-host/api/v1", // optional
  serviceWorkerPath: "/sw.js", // optional
  autoRegister: true, // optional, default true
})

await flowpush.requestPermission()
await flowpush.subscribe()

API

Constructor

new FlowPush(options)

Options:

• appKey: string (required)
• apiUrl: string (optional)
• serviceWorkerPath: string (optional)
• autoRegister: boolean (optional)

Defaults used by the current implementation:

• apiUrl: https://flow-push-api.vercel.app/api/v1
• serviceWorkerPath: /sw.js
• autoRegister: true

registerServiceWorker()

await flowpush.registerServiceWorker()

Registers the service worker at serviceWorkerPath.

requestPermission()

const permission = await flowpush.requestPermission()

Requests browser notification permission and returns NotificationPermission.

subscribe(options?)

const result = await flowpush.subscribe({ deviceType: "web" })

Flow:

1. Reads VAPID public key from GET /sdk/config
2. Creates browser PushSubscription
3. Syncs subscription to POST /sdk/devices
4. Stores flowpush_device_id in localStorage

The SDK also stores a stable physical id in localStorage as flowpush_physical_id.

identify(params)

await flowpush.identify({
  userId: "user_123",
  attributes: {
    plan: "pro",
    locale: "en",
  },
})

Calls POST /sdk/identify and links the current device (or physical id) to a user.

unsubscribe()

await flowpush.unsubscribe()

Unsubscribes from browser push and calls DELETE /sdk/devices with the endpoint.

Backend Endpoints Expected

The SDK expects these API routes under apiUrl:

• GET /sdk/config
• POST /sdk/devices
• POST /sdk/identify
• DELETE /sdk/devices

Each request includes the x-app-key header.

Common Issues

• "Notification permission not granted": call requestPermission first and ensure user accepted.
• "Failed to fetch config": verify apiUrl and CORS settings.
• "VAPID key not configured for this App": configure VAPID keys for the WEB app.
• Service worker not found: confirm sw.js is publicly served and serviceWorkerPath matches.

TypeScript

This package ships type declarations in dist/index.d.ts and dist/index.d.mts.

License

MIT