Web — Push Notifications

Introduction

Lerix delivers web push using the standard Web Push protocol (VAPID) — the same open standard Chrome, Firefox, Edge, and modern Safari all implement natively. No Firebase project, no OneSignal account — Lerix generates and manages the key pair for you.

This is a separate package from the Flutter SDK — @lerix-dev/lerix-js is a small, framework-agnostic JS/TS library for non-Flutter web apps (React, Vue, plain HTML, etc.). If your app is built with Flutter — including Flutter Web — don’t use this package; the lerix Flutter package supports iOS, Android, and Web natively from one package with one API. See Flutter — Push Notifications instead.

1. Install

npm install @lerix-dev/lerix-js

Or drop the pre-built script directly into a page with no build step:

<script src="https://unpkg.com/@lerix-dev/lerix-js/dist/lerix.global.js"></script>

2. Copy the service worker

Web Push requires a service worker file served from your site’s own origin — a plain <script> import can’t register one for you. Copy node_modules/@lerix-dev/lerix-js/sw/lerix-sw.js to your site’s public root so it’s reachable at https://yoursite.com/lerix-sw.js (any path works, as long as you pass it to subscribe() if it’s not at that default).

3. Generate a Web Push key

From the dashboard: Notifications → Settings → Web Push → Generate keys. This is a one-click step — Lerix generates and stores the VAPID key pair for the project; there’s nothing to copy into your code.

4. Use it

import { Lerix } from "@lerix-dev/lerix-js";

Lerix.init({
  apiKey: "your-api-key",
  projectId: "your-project-slug",
});

await Lerix.notifications.init();

Lerix.notifications.setOnNotificationReceived((payload) => {
  // Fired while a tab is open.
  console.log(payload.title, payload.body);
});

Lerix.notifications.setOnNotificationTapped((payload) => {
  // Fired when the user clicks the notification — including one that
  // opened the page from a fully closed tab.
  const screen = payload.metadata.screen;
});

// Prompts for permission and subscribes this browser.
const deviceId = await Lerix.notifications.subscribe();
// `deviceId` is what you pass in `deviceTokens` when sending a notification
// to this browser specifically, from the dashboard or the REST API.

API

Method	Description
`Lerix.init(config)`	Configures the SDK. Call once.
`Lerix.notifications.init()`	Registers this app/user with the backend. Call before anything else on `notifications`.
`requestPermission()`	Prompts for notification permission. Returns `true` if granted.
`checkPermissionStatus()`	`"granted"`, `"denied"`, `"default"`, or `"unsupported"`.
`subscribe(swPath?)`	Registers the service worker and subscribes to push. Returns the device id.
`getDeviceId()`	The device id from the last `subscribe()` call, if any.
`setOnNotificationReceived(cb)`	Fired while a tab is open.
`setOnNotificationTapped(cb)`	Fired on click — delivered reliably even from a closed-tab tap, via the same cold-start recovery pattern the mobile SDK uses.

The notification payload

Both callbacks receive an LerixNotificationPayload — the same shape the Flutter SDK’s model uses:

interface LerixNotificationPayload {
  notificationId: string | null;
  title: string | null;
  body: string | null;
  metadata: Record<string, unknown>;
  imageUrl: string | null;
}

Sending an image

Set imageUrl when sending — from the dashboard’s Send notification tab, or the REST API’s imageUrl parameter. Unlike iOS, this works automatically on the web with no extra setup: the service worker renders it directly as the notification’s icon/image.

Sending metadata

Set metadata when sending — delivered back to the page inside payload.metadata, for routing a tap to a specific in-app view, for example. See Sending metadata for the full parameter details (identical across every platform).

Custom sound is not supported for web push. The Web Notifications API doesn’t expose a way to set a custom notification sound across browsers, so the dashboard/API’s sound parameter is ignored for web recipients — it only applies to iOS and Android.

Target a user on every device

If your product also ships on other platforms (web, mobile or desktop), add them to the same project and link each install to your own user ID after login. Your backend can then send to externalUserIds and reach that person on every device in one request.

await Lerix.setUser('user_123'); // after login
await Lerix.clearUser();         // on logout

See Identify users for identity verification and a sending example.

Browser support

Chrome, Firefox, and Edge support Web Push fully. Safari requires macOS 13+ or iOS 16.4+ — older Safari doesn’t support the standard at all.

Flutter Web

Don’t use this JS SDK for a Flutter app, even a Flutter Web build — the lerix Flutter package supports iOS, Android, and Web natively from a single package, calling the browser’s Push API directly with no separate JS dependency at all. Same Lerix.notifications.* calls, same LerixNotificationPayload shape, on every platform:

import 'package:lerix_flutter/lerix_flutter.dart';

void main() {
  Lerix.init(
    url: 'https://api.lerix.dev',
    apiKey: 'your-api-key',
    projectId: 'your-project-slug',
    builder: () => runApp(const MyApp()),
  );
}

// Later:
await Lerix.notifications.init();

Lerix.notifications.setOnNotificationTapped((payload) {
  final screen = payload.metadata['screen'];
});

final granted = await Lerix.notifications.requestPermissions();
if (granted) {
  final deviceId = await Lerix.notifications.getDeviceId();
}

See Flutter — Push Notifications for the (two-step) Flutter Web setup and the small platform differences worth knowing about.

Getting started

Frameworks

Modules

Developers

Web — Push Notifications

Introduction

1. Install

2. Copy the service worker

3. Generate a Web Push key

4. Use it

API

The notification payload

Sending an image

Sending metadata

Target a user on every device

Browser support

Flutter Web

​Introduction

​1. Install

​2. Copy the service worker

​3. Generate a Web Push key

​4. Use it

​API

​The notification payload

​Sending an image

​Sending metadata

​Target a user on every device

​Browser support

​Flutter Web

Introduction

1. Install

2. Copy the service worker

3. Generate a Web Push key

4. Use it

API

The notification payload

Sending an image

Sending metadata

Target a user on every device

Browser support

Flutter Web