Push Notifications

Web Push

Send web push notifications to engage users even when they're not on your site.

Cross-Browser

Chrome, Firefox, Safari, Edge

Rich Content

Images, actions, badges

Segmentation

Target specific user groups

Preferences

User-controlled categories

Request Permission

Ask users for notification permission:

Client-side (React)
'use client'

import { usePushNotifications } from '@sylphx/platform-sdk/react'

export function NotificationPermission() {
  const { permission, requestPermission, isSupported } = usePushNotifications()

  if (!isSupported) {
    return <p>Push notifications are not supported in your browser.</p>
  }

  if (permission === 'granted') {
    return <p>Notifications enabled ✓</p>
  }

  if (permission === 'denied') {
    return <p>Notifications blocked. Please enable in browser settings.</p>
  }

  return (
    <button onClick={requestPermission}>
      Enable Notifications
    </button>
  )
}

Subscribe User

After permission is granted, subscribe the user:

'use client'

import { usePushNotifications } from '@sylphx/platform-sdk/react'
import { useUser } from '@sylphx/platform-sdk/react'

export function EnableNotifications() {
  const { user } = useUser()
  const { subscribe, unsubscribe, isSubscribed } = usePushNotifications()

  const handleToggle = async () => {
    if (isSubscribed) {
      await unsubscribe()
    } else {
      await subscribe() // Automatically registers with platform
    }
  }

  return (
    <label>
      <input
        type="checkbox"
        checked={isSubscribed}
        onChange={handleToggle}
      />
      Receive push notifications
    </label>
  )
}

Send Notifications

Send notifications from your server:

Server-side
import { platform } from '@/lib/platform'

// Send to a specific user
await platform.notifications.send({
  userId: user.id,
  title: 'New message',
  body: 'You have a new message from John',
  icon: '/icon-192.png',
  data: {
    url: '/messages/123',
  },
})

// Send to multiple users
await platform.notifications.sendBatch({
  userIds: [user1.id, user2.id, user3.id],
  title: 'New feature available!',
  body: 'Check out our new dashboard.',
})

Notification Options

Customize notification appearance:

await platform.notifications.send({
  userId: user.id,

  // Required
  title: 'Order shipped!',
  body: 'Your order #123 is on its way.',

  // Optional
  icon: '/icon-192.png',           // Notification icon
  badge: '/badge-72.png',          // Badge icon (mobile)
  image: '/order-preview.jpg',     // Large image
  tag: 'order-123',                // Replace previous with same tag
  requireInteraction: true,        // Don't auto-dismiss

  // Actions
  actions: [
    { action: 'track', title: 'Track Order' },
    { action: 'dismiss', title: 'Dismiss' },
  ],

  // Custom data for handling clicks
  data: {
    orderId: '123',
    url: '/orders/123',
  },
})
PropertyTypeDescription
titlerequiredNotification title
bodyrequiredNotification body text
iconstringSmall icon URL
badgestringBadge icon for mobile
imagestringLarge image URL
tagstringGroup notifications with same tag
actionsarrayAction buttons
dataobjectCustom data for click handler

Handle Clicks

Handle clicks in your service worker:

public/sw.js
self.addEventListener('notificationclick', (event) => {
  event.notification.close()

  const data = event.notification.data
  const action = event.action

  if (action === 'track') {
    clients.openWindow('/orders/' + data.orderId + '/tracking')
  } else {
    clients.openWindow(data.url || '/')
  }
})

SDK Service Worker

The SDK includes a pre-built service worker. Import it in your service worker or use the standalone version.

Broadcast

Send notifications to all subscribers:

// Send to all subscribed users
await platform.notifications.broadcast({
  title: 'Maintenance scheduled',
  body: 'We will be down for maintenance at 2am UTC.',
  segment: 'all', // or specific segments
})

// Send to a segment
await platform.notifications.broadcast({
  title: 'Pro feature update',
  body: 'Check out new features in your Pro plan.',
  segment: 'pro-users',
})

User Preferences

Let users control notification types:

'use client'

import { usePushNotifications } from '@sylphx/platform-sdk/react'

export function NotificationPreferences() {
  const { preferences, updatePreferences } = usePushNotifications()

  return (
    <div className="space-y-4">
      <h3>Notification Preferences</h3>

      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          checked={preferences.marketing}
          onChange={(e) => updatePreferences({ marketing: e.target.checked })}
        />
        Marketing updates
      </label>

      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          checked={preferences.orders}
          onChange={(e) => updatePreferences({ orders: e.target.checked })}
        />
        Order updates
      </label>

      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          checked={preferences.messages}
          onChange={(e) => updatePreferences({ messages: e.target.checked })}
        />
        New messages
      </label>
    </div>
  )
}

Browser Support

Chrome

Desktop & Android

Firefox

Desktop & Android

Edge

Desktop

Safari

macOS 13+

Opera

Desktop

iOS Safari

Not supported

iOS Push

iOS Safari doesn't support web push. Use a native app for iOS push notifications.