Snippet & SDK reference

The SDK is a single async script under 2 KB gzipped. It adds one global, window.PushSvc, and never throws into your page.

On WordPress? Our plugin injects the snippet and serves the service worker for you, so skip this page entirely.

Installation options

<script async
  src="//cdn.pushnotificationservice.com/sdk/v1.js"
  data-site="YOUR_SITE_ID"
  data-sw="/pns-sw.js"
  data-prompt="manual"
  data-tags="news,product"></script>

Attribute	Default	Description
`data-site`	—	Required. Your site's public ID.
`data-sw`	`/pns-sw.js`	Path to your service worker file.
`data-prompt`	`manual`	`auto` prompts shortly after load; `manual` waits for `subscribe()`.
`data-tags`	—	Comma-separated tags applied when a visitor subscribes.

JavaScript API

All methods return promises and never reject: failures resolve to a safe value.

Method	Returns	Description
`PushSvc.supported`	`boolean`	Whether this browser supports web push (see the iOS note below).
`PushSvc.subscribe({tags})`	`Promise<string\|null>`	Requests permission and subscribes. Resolves to the subscriber ID, or `null` if declined.
`PushSvc.unsubscribe()`	`Promise<void>`	Unsubscribes the current browser.
`PushSvc.isSubscribed()`	`Promise<boolean>`	Whether this browser currently holds a subscription.
`PushSvc.tag(...names)`	`Promise<void>`	Adds tags to the current subscriber.
`PushSvc.untag(...names)`	`Promise<void>`	Removes tags from the current subscriber.
`PushSvc.permission()`	`string`	`granted`, `denied`, `default`, or `unsupported`.

// Subscribe with tags from a button click
document.querySelector('#notify').addEventListener('click', async () => {
  const id = await PushSvc.subscribe({ tags: ['news'] });
  if (id) console.log('Subscribed:', id);
});

Any element with data-pns-subscribe becomes a live subscribe button: the SDK wires the click, reflects the visitor's real subscription state, and never shows a button that can't work. Ship it with the hidden attribute — the SDK reveals it once it knows what to show:

<button hidden data-pns-subscribe
        data-subscribed-text="You're subscribed"
        data-denied-text="Notifications are blocked in this browser"
        data-ios-hint="To get notified, add this site to your Home Screen (Share → Add
                       to Home Screen), then open it from there and subscribe.">
  Notify me about new posts
</button>

Attribute	Description
`data-subscribed-text`	Label shown when the visitor is (or becomes) subscribed.
`data-denied-text`	Label shown when notification permission is blocked. The button is disabled.
`data-ios-hint`	Text shown on iOS/iPadOS Safari tabs, where Apple only allows push for Home Screen web apps. Omit it and the button stays hidden there instead.
`data-tags`	Comma-separated tags applied when this button subscribes, in addition to the script tag's `data-tags`.

The element's current state is mirrored in data-pns-state (ready, subscribed, denied, ios, unsupported) for styling — for example, to render the iOS hint as plain text rather than a disabled button:

[data-pns-state="ios"] { border: none; background: none; opacity: .8; font-size: .9em; }

Elements must be in the DOM when the SDK initializes; for buttons added later, call PushSvc.subscribe() from your own handler as above. The WordPress plugin ships this same button as a shortcode.

Safari & iOS

Desktop Safari 16.4+ supports web push directly. On iOS/iPadOS, Apple only permits push for sites the user has installed to their Home Screen as a web app (requires a web app manifest). Before that, PushSvc.supported is false and subscribe() resolves to null. Use a declarative subscribe button with data-ios-hint and iOS visitors get “Add to Home Screen” instructions automatically; if you build your own UI, detect iOS Safari and show that hint rather than a permission prompt.

Notification display

Every push shows a notification. Browsers penalize senders whose pushes stay silent, so the service worker always displays one. Clicks open the campaign's URL (via a signed redirect we use to count click-through), and an optional “Unsubscribe” action is added automatically.

Endpoint rotation