createPushary

Creates a new Pushary instance.

const pushary = createPushary(config: PusharyConfig): PusharyInstance

PusharyConfig

interface PusharyConfig {
  siteKey: string
  apiUrl?: string
  autoPrompt?: boolean
  promptDelay?: number
  debug?: boolean
  onSubscribe?: (subscription: PushSubscription) => void
  onPermissionDenied?: () => void
  onNotSupported?: () => void
  onNotificationClick?: (url: string, data: NotificationData) => boolean | void
}

PusharyInstance

interface PusharyInstance {
  promptForPermission(): Promise<PushSubscription | null>
  subscribe(): Promise<PushSubscription | null>
  unsubscribe(): Promise<void>
  setExternalId(externalId: string): Promise<void>
  setTags(tags: Record<string, string>): Promise<void>
  processRetryQueue(): Promise<void>
  isSupported(): boolean
}

Methods

promptForPermission

Requests notification permission from the user. If permission is already granted, subscribes immediately.

const subscription = await pushary.promptForPermission()

if (subscription) {
  console.log('User subscribed:', subscription.endpoint)
} else {
  console.log('Permission denied or not supported')
}

Subscribes to push notifications. Requires permission to already be granted.

if (Notification.permission === 'granted') {
  const subscription = await pushary.subscribe()
}

unsubscribe

Unsubscribes the user from push notifications.

await pushary.unsubscribe()

setExternalId

Associates your internal user ID with the subscriber. Enables targeting by user ID from your backend.

await pushary.setExternalId('user-123')

setTags

Sets tags for subscriber segmentation.

await pushary.setTags({
  plan: 'premium',
  interests: 'sports,news',
})

isSupported

Checks if push notifications are supported in the current browser.

if (pushary.isSupported()) {
  // Push is available
}

Callbacks

onSubscribe

Called when the user successfully subscribes.

createPushary({
  siteKey: 'pk_xxx',
  onSubscribe: (subscription) => {
    console.log('Subscribed:', subscription.endpoint)
  },
})

onPermissionDenied

Called when the user denies notification permission.

createPushary({
  siteKey: 'pk_xxx',
  onPermissionDenied: () => {
    console.log('User denied notifications')
  },
})

onNotificationClick

Called when a notification is clicked. Return false to prevent default navigation.

createPushary({
  siteKey: 'pk_xxx',
  onNotificationClick: (url, data) => {
    console.log('Clicked:', url, data)
    
    if (data.campaignId === 'special') {
      window.location.href = '/special-page'
      return false
    }
    
    return true
  },
})

Utility Functions

The SDK exports utility functions for common tasks like device detection and URL handling.

isPushSupported

Checks if push notifications are supported in the current environment.

import { isPushSupported } from '@pushary/sdk'

if (isPushSupported()) {
  console.log('Push notifications are supported')
}

Returns: boolean - true if service workers, PushManager, and Notification API are available.

getDeviceInfo

Gets detailed information about the current device and browser.

import { getDeviceInfo } from '@pushary/sdk'

const info = getDeviceInfo(navigator)
console.log(info)

Returns: DeviceInfo object with:

userAgent: string - Full user agent string
browser: string - Browser name (Chrome, Firefox, Safari, Edge, Opera, Unknown)
os: string - Operating system (Windows, macOS, Linux, Android, iOS, Unknown)
deviceType: string - Device type (desktop, mobile, tablet)
language: string - Browser language
timezone: string - User's timezone

detectBrowser

Detects the browser from a user agent string.

import { detectBrowser } from '@pushary/sdk'

const browser = detectBrowser(navigator.userAgent)
console.log(browser)

Parameters: userAgent: string

detectOS

Detects the operating system from a user agent string.

import { detectOS } from '@pushary/sdk'

const os = detectOS(navigator.userAgent)
console.log(os)

Parameters: userAgent: string

detectDeviceType

Detects the device type from a user agent string.

import { detectDeviceType } from '@pushary/sdk'

const deviceType = detectDeviceType(navigator.userAgent)
console.log(deviceType)

Parameters: userAgent: string

Returns: 'desktop' | 'mobile' | 'tablet'

navigateToUrl

Navigates to a URL by setting window.location.href.

import { navigateToUrl } from '@pushary/sdk'

navigateToUrl('https://example.com/page')

Parameters: url: string

Returns: void

isNavigationValid

Checks if a pending navigation is still valid (not expired).

import { isNavigationValid } from '@pushary/sdk'

const pending = { timestamp: Date.now(), url: '/page' }
if (isNavigationValid(pending)) {
  console.log('Navigation is still valid')
}

Parameters: pending: PendingNavigation - Object with timestamp and url

Returns: boolean - true if navigation hasn't expired (within 30 seconds)

isExternalUrl

Checks if a URL is external (different origin).

import { isExternalUrl } from '@pushary/sdk'

if (isExternalUrl('https://example.com', window.location.origin)) {
  console.log('External URL')
}

Parameters:

url: string - URL to check
origin: string - Current origin to compare against

Returns: boolean - true if URL has a different origin

urlBase64ToUint8Array

Converts a base64 URL-encoded string to a Uint8Array. Useful for VAPID keys.

import { urlBase64ToUint8Array } from '@pushary/sdk'

const vapidPublicKey = 'BEl62iUY...'
const uint8Array = urlBase64ToUint8Array(vapidPublicKey)

Parameters: base64String: string - URL-safe base64 string

Returns: Uint8Array - Decoded byte array

Browser Support

Browser	Minimum Version
Chrome	50+
Firefox	44+
Safari	16+ (macOS & iOS)
Edge	17+
Opera	37+

Internal Endpoints

These endpoints are used internally by the SDK. You typically don't need to call them directly, but they're documented here for reference.

Update Subscription

POST /api/v1/subscription-change

Updates a subscriber's push subscription endpoint when their browser subscription changes (e.g., after reinstalling the browser or clearing data).

Used by: The SDK automatically calls this when it detects a subscription change.

Request Body

{
  "oldEndpoint": "https://fcm.googleapis.com/...",
  "newSubscription": {
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": {
      "p256dh": "base64-encoded-key",
      "auth": "base64-encoded-key"
    }
  }
}

Response

{
  "success": true,
  "subscriberId": "sub_abc123"
}

Get Site Configuration

GET /api/v1/site/:siteSlug

Retrieves public site configuration including branding settings. This is used for the hosted subscription page and widget customization.

Used by: Subscription pages and embed widgets.

Response

{
  "name": "My Site",
  "logoUrl": "https://example.com/logo.png",
  "domain": "example.com",
  "siteKey": "pk_xxx",
  "branding": {
    "primaryColor": "#007bff",
    "buttonText": "Subscribe"
  }
}

createPushary

Creates a new Pushary instance.

const pushary = createPushary(config: PusharyConfig): PusharyInstance

PusharyConfig

interface PusharyConfig {
  siteKey: string
  apiUrl?: string
  autoPrompt?: boolean
  promptDelay?: number
  debug?: boolean
  onSubscribe?: (subscription: PushSubscription) => void
  onPermissionDenied?: () => void
  onNotSupported?: () => void
  onNotificationClick?: (url: string, data: NotificationData) => boolean | void
}

PusharyInstance

interface PusharyInstance {
  promptForPermission(): Promise<PushSubscription | null>
  subscribe(): Promise<PushSubscription | null>
  unsubscribe(): Promise<void>
  setExternalId(externalId: string): Promise<void>
  setTags(tags: Record<string, string>): Promise<void>
  processRetryQueue(): Promise<void>
  isSupported(): boolean
}

Methods

promptForPermission

Requests notification permission from the user. If permission is already granted, subscribes immediately.

const subscription = await pushary.promptForPermission()

if (subscription) {
  console.log('User subscribed:', subscription.endpoint)
} else {
  console.log('Permission denied or not supported')
}

Subscribes to push notifications. Requires permission to already be granted.

if (Notification.permission === 'granted') {
  const subscription = await pushary.subscribe()
}

unsubscribe

Unsubscribes the user from push notifications.

await pushary.unsubscribe()

setExternalId

Associates your internal user ID with the subscriber. Enables targeting by user ID from your backend.

await pushary.setExternalId('user-123')

setTags

Sets tags for subscriber segmentation.

await pushary.setTags({
  plan: 'premium',
  interests: 'sports,news',
})

isSupported

Checks if push notifications are supported in the current browser.

if (pushary.isSupported()) {
  // Push is available
}

Callbacks

onSubscribe

Called when the user successfully subscribes.

createPushary({
  siteKey: 'pk_xxx',
  onSubscribe: (subscription) => {
    console.log('Subscribed:', subscription.endpoint)
  },
})

onPermissionDenied

Called when the user denies notification permission.

createPushary({
  siteKey: 'pk_xxx',
  onPermissionDenied: () => {
    console.log('User denied notifications')
  },
})

onNotificationClick

Called when a notification is clicked. Return false to prevent default navigation.

createPushary({
  siteKey: 'pk_xxx',
  onNotificationClick: (url, data) => {
    console.log('Clicked:', url, data)
    
    if (data.campaignId === 'special') {
      window.location.href = '/special-page'
      return false
    }
    
    return true
  },
})

Utility Functions

The SDK exports utility functions for common tasks like device detection and URL handling.

isPushSupported

Checks if push notifications are supported in the current environment.

import { isPushSupported } from '@pushary/sdk'

if (isPushSupported()) {
  console.log('Push notifications are supported')
}

Returns: boolean - true if service workers, PushManager, and Notification API are available.

getDeviceInfo

Gets detailed information about the current device and browser.

import { getDeviceInfo } from '@pushary/sdk'

const info = getDeviceInfo(navigator)
console.log(info)

Returns: DeviceInfo object with:

userAgent: string - Full user agent string
browser: string - Browser name (Chrome, Firefox, Safari, Edge, Opera, Unknown)
os: string - Operating system (Windows, macOS, Linux, Android, iOS, Unknown)
deviceType: string - Device type (desktop, mobile, tablet)
language: string - Browser language
timezone: string - User's timezone

detectBrowser

Detects the browser from a user agent string.

import { detectBrowser } from '@pushary/sdk'

const browser = detectBrowser(navigator.userAgent)
console.log(browser)

Parameters: userAgent: string

detectOS

Detects the operating system from a user agent string.

import { detectOS } from '@pushary/sdk'

const os = detectOS(navigator.userAgent)
console.log(os)

Parameters: userAgent: string

detectDeviceType

Detects the device type from a user agent string.

import { detectDeviceType } from '@pushary/sdk'

const deviceType = detectDeviceType(navigator.userAgent)
console.log(deviceType)

Parameters: userAgent: string

Returns: 'desktop' | 'mobile' | 'tablet'

navigateToUrl

Navigates to a URL by setting window.location.href.

import { navigateToUrl } from '@pushary/sdk'

navigateToUrl('https://example.com/page')

Parameters: url: string

Returns: void

isNavigationValid

Checks if a pending navigation is still valid (not expired).

import { isNavigationValid } from '@pushary/sdk'

const pending = { timestamp: Date.now(), url: '/page' }
if (isNavigationValid(pending)) {
  console.log('Navigation is still valid')
}

Parameters: pending: PendingNavigation - Object with timestamp and url

Returns: boolean - true if navigation hasn't expired (within 30 seconds)

isExternalUrl

Checks if a URL is external (different origin).

import { isExternalUrl } from '@pushary/sdk'

if (isExternalUrl('https://example.com', window.location.origin)) {
  console.log('External URL')
}

Parameters:

url: string - URL to check
origin: string - Current origin to compare against

Returns: boolean - true if URL has a different origin

urlBase64ToUint8Array

Converts a base64 URL-encoded string to a Uint8Array. Useful for VAPID keys.

import { urlBase64ToUint8Array } from '@pushary/sdk'

const vapidPublicKey = 'BEl62iUY...'
const uint8Array = urlBase64ToUint8Array(vapidPublicKey)

Parameters: base64String: string - URL-safe base64 string

Returns: Uint8Array - Decoded byte array

Browser Support

Browser	Minimum Version
Chrome	50+
Firefox	44+
Safari	16+ (macOS & iOS)
Edge	17+
Opera	37+

Internal Endpoints

These endpoints are used internally by the SDK. You typically don't need to call them directly, but they're documented here for reference.

Update Subscription

POST /api/v1/subscription-change

Updates a subscriber's push subscription endpoint when their browser subscription changes (e.g., after reinstalling the browser or clearing data).

Used by: The SDK automatically calls this when it detects a subscription change.

Request Body

{
  "oldEndpoint": "https://fcm.googleapis.com/...",
  "newSubscription": {
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": {
      "p256dh": "base64-encoded-key",
      "auth": "base64-encoded-key"
    }
  }
}

Response

{
  "success": true,
  "subscriberId": "sub_abc123"
}

Get Site Configuration

GET /api/v1/site/:siteSlug

Retrieves public site configuration including branding settings. This is used for the hosted subscription page and widget customization.

Used by: Subscription pages and embed widgets.

Response

{
  "name": "My Site",
  "logoUrl": "https://example.com/logo.png",
  "domain": "example.com",
  "siteKey": "pk_xxx",
  "branding": {
    "primaryColor": "#007bff",
    "buttonText": "Subscribe"
  }
}

API Reference

On this page

API Reference

On this page