Skip to documentation content

PWA setup

Use @palmpush/pwa when your own Progressive Web App should receive palmpush notifications.

This registers a browser as a receiving device. To send messages from scripts or a backend, use the HTTP API or JavaScript.

This is useful when you want notifications to feel like they belong to your web app. For example, the notification can use your PWA app icon instead of the palmpush iOS app icon.

Create a listener in the iOS app first, then register the PWA with that listener token.

Install

bash
npm install @palmpush/pwa

Add the service worker

Browser push notifications are delivered through a service worker. For most Vite, Next.js, and Create React App projects, run this from the web app root:

bash
npx @palmpush/pwa init

This copies the worker to:

txt
public/palmpush-sw.js

Your production site must serve it at:

txt
/palmpush-sw.js

React apps

If your app uses React, for example Next.js, Remix, Vite React, or Create React App, the easiest setup is the packaged button.

The button checks browser support, asks for notification permission after the user clicks it, and registers the browser with palmpush. You do not need to call checkPermission, askForPermission, or registerListener yourself.

You still need the install and service worker setup above.

For one listener:

jsx
import { PalmpushPwaButton } from '@palmpush/pwa/react';

export function PushSettings() {
  return <PalmpushPwaButton listenerToken="abc123abc123abc123abc123abc123ab" />;
}

For multiple listeners:

jsx
import { PalmpushPwaButton } from '@palmpush/pwa/react';

export function PushSettings() {
  return (
    <PalmpushPwaButton
      listenerTokens={[
        'abc123abc123abc123abc123abc123ab',
        'def456def456def456def456def456de',
      ]}
    />
  );
}

You can also use listenerId or listenerIds if that name fits your app better. Do not mix token props and id props in the same button.

Manual setup

Use the manual SDK functions if you do not use React or if you need a custom setup flow.

Register one listener

js
import {
  askForPermission,
  checkPermission,
  registerListener,
} from '@palmpush/pwa';

const status = checkPermission();

if (!status.granted) {
  await askForPermission();
}

await registerListener({
  listenerToken: 'abc123abc123abc123abc123abc123ab',
});

For a one-click setup button, call registration from a user gesture:

js
await registerListener({
  listenerToken: 'abc123abc123abc123abc123abc123ab',
  requestPermission: true,
});

Register multiple listeners

js
import { registerListeners } from '@palmpush/pwa';

await registerListeners({
  listenerTokens: [
    'abc123abc123abc123abc123abc123ab',
    'def456def456def456def456def456de',
  ],
});

The same browser installation can subscribe to multiple listeners.

Images, links, and avatars

The 0.2.0 or newer worker passes imageUrl to the browser's notification image option. It keeps your PWA icon and badge. Image display depends on the browser; text still works where notification images are unsupported. See browser compatibility. The 0.1.1 worker does not display attachments.

Send an absolute HTTPS image URL, up to 2,048 characters, without credentials, spaces, or control characters. The browser must be able to download it without login. See Images for hosting guidance; the native iOS attachment format and 1 MiB limit are separate from browser display capabilities.

HTTP(S) tap destinations already work with the 0.1.1 worker. The updated worker validates the URL, focuses an existing matching window where possible, and otherwise opens it. Without a URL, or with an invalid or native-only app scheme, it opens the PWA root. Existing relative worker destinations remain supported; the public API requires absolute URLs.

Use the HTTP API, palmpush 0.3.0 or newer, or @palmpush/mcp 0.2.0 or newer to send both fields. PWA registration inputs do not change. The iOS app's listener avatars and matching History navigation are separate from the PWA worker. Updating the iOS app does not update a PWA service worker.

Update an existing service worker

After upgrading to @palmpush/pwa 0.2.0 or newer, copy and deploy the new worker. Updating the dependency alone leaves an already copied worker unchanged.

For an unmodified generated worker, run from the receiving web app:

bash
npx @palmpush/pwa init --force

Reuse your original --public-dir and --filename options if needed. If your app owns a custom worker, merge the updated push/click handlers and their helper functions into it instead of overwriting your other handlers.

Deploy at the same worker URL and scope. Reopen the PWA to let the browser check for the update; if the old worker is waiting to be replaced, close existing PWA windows and reopen. Existing subscriptions and device IDs can be reused. Test with a newly sent image-and-link message after the new worker becomes active.

iOS note

On iOS, Web Push works for Home Screen web apps. A normal Safari tab can run the setup code, but it cannot receive iOS Web Push notifications.

Keep listener tokens private

A listener token is a secret: anyone who can read it can send notifications, subscribe another device, and change shared listener settings.

If only signed-in users should register for a listener, load the token after authentication from your database or backend API instead of hardcoding it in a public bundle. Hardcoding can be fine for public opt-in notifications, but it also means every visitor can access that listener token.