Web SDK

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

Installation

Add the loader script to your HTML <head> or before </body>:

html

<script src="https://push.notirix.com/push-loader.js"></script>

Then initialize on page load:

const sdk = initNotirix({
  apiBaseUrl:     'https://push.notirix.com',
  appId:          'YOUR_APP_ID',
  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
})
await sdk.init()

// Subscribe with the default prompt configured in Admin
const result = await sdk.subscribeWithPrompt()
console.log(result.status) // 'subscribed'

💡

The vapidPublicKey is found in your app settings under Settings → VAPID Keys.

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

You control the UI. SDK handles subscription silently.

// Override type and branding per-call
const result = await sdk.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.

const result = await sdk.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:

await sdk.subscribeWithPrompt({
  type:             'slide',
  slidePosition:    'bottom',   // 'top' | 'bottom'
  accentColor:      '#2ECFB1',
  borderRadius:     '12px',
  allowButtonColor: '#2ECFB1',
  laterButtonColor: 'transparent',
})

Methods

sdk.init()

Registers the service worker and fetches prompt config from the server. Call once on page load.

const sdk = initNotirix({ apiBaseUrl, appId, vapidPublicKey })
await sdk.init()

sdk.subscribeWithPrompt(options?)

Shows the permission prompt and subscribes the user. Returns a status object.

const result = await sdk.subscribeWithPrompt()
// result.status: 'subscribed' | 'denied' | 'cancelled' | 'already-subscribed'
//                'ios-pwa-required' | 'limit-reached'

sdk.setTag(userId, key, value, apiKey)

Sets a tag on the current user. Tags are used for audience segmentation.

sdk.getPermissionStatus()

Returns the current browser notification permission: "granted" | "denied" | "default".

User tags

Tags let you segment subscribers. Set them from the SDK, API, or Admin UI.

// Set tags after subscription
await sdk.setTag(
  'user-123',      // externalId — your internal user ID
  'plan',          // tag key
  'premium',       // tag value
  'YOUR_API_KEY',  // app API key
)

// Multiple tags
await sdk.setTag(userId, 'last_purchase_category', 'electronics', apiKey)
await sdk.setTag(userId, 'total_orders', 14, apiKey)

💡

Tags are key-value pairs. Values can be strings, numbers, or booleans. Existing keys are overwritten (upsert).