Web SDK

Web SDK

Add push notifications to any website in minutes. The SDK handles subscription prompts, service worker registration, and token management automatically.

Installation

1. Create two small loader files in the root of your site. The SDK and the service worker themselves are loaded from Notirix — these files only point to them.

push-loader.js

js
export { NotirixSDK, initNotirix } from "https://push.notirix.com/sdk/index.js";

push-sw.js

js
var MAIN_SW_URL = "https://push.notirix.com/worker/main-sw.js";
try { importScripts(MAIN_SW_URL); } catch(e) {
  self.addEventListener("push", function(){});
  self.addEventListener("notificationclick", function(e){ e.notification.close(); });
}
ℹ️
Both files must be served from the root of your domain (e.g. https://example.com/push-sw.js) — a service worker only controls pages inside its own folder. Your site must use HTTPS.

2. Initialize the SDK on every page where push should work:

html
<script type="module">
  import { initNotirix } from "/push-loader.js";

  const notirix = initNotirix({
    apiBaseUrl:     "https://push.notirix.com",
    appId:          "YOUR_APP_ID",
    vapidPublicKey: "YOUR_VAPID_PUBLIC_KEY",
  });

  // Show the prompt configured in Admin → Configuration
  const result = await notirix.subscribeWithPrompt();
  console.log(result.status); // 'subscribed'
</script>
💡
The App ID and vapidPublicKey are in Admin → Settings. You don't need to call any separate init method: the SDK registers the service worker and loads the prompt configuration on the first call.

Prompt types

Notirix supports five prompt styles. Configure the default in Admin → Configuration, or override per-call in subscribeWithPrompt().

🪟
modal

Centered overlay with branded header. Default style.

📌
slide

Full-width bar that slides from top or bottom.

🔔
bell

Floating FAB bell button + popover card.

💬
native

Browser's built-in permission dialog. No custom UI.

⚙️
custom

No Notirix UI on page load — you decide when to ask. Calling subscribeWithPrompt() with branding options shows the modal.

js
// Override type and branding per-call
const result = await notirix.subscribeWithPrompt({
  type:         'modal',
  brandName:    'My Store',
  accentColor:  '#FF6B35',
  title:        'Get sale alerts',
  description:  'Be first to know about flash deals.',
  allowLabel:   'Yes, notify me',
  laterLabel:   'Maybe later',
})

iOS PWA support

Web Push on iOS requires the user to install the site as a PWA (iOS 16.4+). The SDK detects iOS Safari and shows an "Add to Home Screen" banner automatically.

js
const result = await notirix.subscribeWithPrompt()

if (result.status === 'ios-pwa-required') {
  // SDK already showed the "Add to Home Screen" banner.
  // You can also show your own message:
  console.log('User needs to install the PWA first')
}
ℹ️
subscribeWithPrompt() returns "ios-pwa-required" when the user is on iOS Safari outside standalone mode. The banner is shown automatically — no extra code needed.

Customization

Pass options to subscribeWithPrompt() to override the server config:

js
await notirix.subscribeWithPrompt({
  type:             'slide',
  slidePosition:    'bottom',   // 'top' | 'bottom'
  accentColor:      '#2ECFB1',
  borderRadius:     '12px',
  allowButtonColor: '#2ECFB1',
  laterButtonColor: 'transparent',
  forceShow:        true,       // ignore a recent "Later" click
})
💡
After the visitor clicks "Later", the prompt is hidden for a while and subscribeWithPrompt() returns "snoozed". Pass forceShow: true when the visitor asks for the prompt explicitly, e.g. by clicking your own "Subscribe" button.

Methods

All methods are available on the object returned by initNotirix(). Methods that take a callback also return a Promise, so you can use either style.

initNotirix(options)

Creates the SDK instance. Options: apiBaseUrl, appId, vapidPublicKey, and optionally externalId, debug, serviceWorkerPath (default "/push-sw.js"). Calling it again with the same appId returns the same instance.

subscribeWithPrompt(options?, callback?)

Shows the permission prompt configured in Admin and subscribes the user. Resolves with { status } — see the table below.

js
const result = await notirix.subscribeWithPrompt()
if (result.status === 'subscribed' || result.status === 'already-subscribed') {
  // the user can receive notifications
}
subscribe(callback?)

Requests permission with the browser's dialog and subscribes, without any Notirix UI. Throws if permission is not granted.

setExternalId(externalId)

Links the subscription to your own user ID. Set it before subscribing (or pass externalId to initNotirix).

sendTags(tags, callback?) / sendTag(key, value, callback?)

Sets one or several tags on the current user. Requires an active subscription.

getTags(callback?)

Returns the current user's tags: [{ key, value }, …].

sendEvent(name, callback?)

Records a custom event for the current user (SDK 1.4.0+). See Custom events below.

getUserId(callback?) / getUser(callback?)

Returns the Notirix user ID / the user profile from the server. null before the first subscription.

getUnreadCount(tag?)

Number of unread push messages of the current user, optionally only with the given message tag. Returns 0 when not subscribed.

isPushSupported()

true if the browser supports web push.

setDebug(enabled)

Turns verbose logging on or off. Logs go to the console and to Admin → SDK Debug Logs.

push([command, ...args])

The same methods in command form — handy in inline scripts where the notirix variable is not in scope.

js
window.Notirix.push(['sendEvent', 'purchase'])
window.Notirix.push(['sendTags', { plan: 'premium' }])

Subscription statuses

StatusMeaning
subscribedThe user allowed notifications and is now subscribed.
already-subscribedThe user was already subscribed.
cancelledThe user closed the prompt without allowing.
deniedNotifications are blocked in the browser.
snoozedThe user clicked "Later" recently — the prompt is hidden for now (see forceShow).
unsupportedThe browser does not support web push.
ios-pwa-requirediOS Safari: the site must be added to the Home Screen first (banner shown automatically).
limit-reachedThe subscriber limit of your plan is reached — no prompt is shown.
app-disabledThe app is disabled — no prompt is shown.

User tags

Tags let you segment subscribers. Set them from the SDK, the REST API, or the Admin UI. Tags need an active subscription — call them after subscribeWithPrompt() has finished.

js
const result = await notirix.subscribeWithPrompt()

if (result.status === 'subscribed' || result.status === 'already-subscribed') {
  // Several tags at once
  await notirix.sendTags({ plan: 'premium', total_orders: 14, interests: ['sports', 'tech'] })

  // A single tag
  await notirix.sendTag('last_purchase_category', 'electronics')

  // Read them back
  const tags = await notirix.getTags() // [{ key: 'plan', value: 'premium' }, …]
}
💡
Tags are key-value pairs. Values can be strings, numbers, booleans or arrays. Existing keys are overwritten (upsert).

Custom events

Report something the user did — a purchase, a sign-up, a completed form. Journeys use these events in the exit rule "Custom event": the user leaves the journey as soon as the event arrives. Available since SDK 1.4.0.

js
// After a successful checkout
await notirix.sendEvent('purchase')

// Callback style
notirix.sendEvent('signup_completed', function () {
  console.log('event sent')
})
ℹ️
Event name: 1–100 characters — letters, digits, _ - .:. Like tags, events need an active subscription: for a visitor who is not subscribed the call is skipped with a console warning. Events are stored for 90 days. To send events from your server, use the REST API.