PWA API Reference

Complete API reference for the CloudSignal PWA SDK.

CloudSignalPWA

Main SDK class that integrates all PWA functionality.

Constructor

new CloudSignalPWA(config: PWAConfig)

Config Options:

Option	Type	Required	Description
`organizationId`	string	Yes	CloudSignal organization UUID
`organizationPublishableKey`	string	Yes	Organization publishable key (`pk_*`). Safe to ship in browser code.
`serviceId`	string	Yes	PWA service UUID
`serviceUrl`	string	No	Service URL (default: `https://pwa.cloudsignal.app`)
`debug`	boolean	No	Enable debug logging
`serviceWorker.path`	string	No	Service worker path (default: `/service-worker.js`)
`serviceWorker.scope`	string	No	Service worker scope (default: `/`)
`heartbeat.interval`	number	No	Heartbeat interval in ms (default: 60000)

Initialization

initialize()

Initialize the PWA client. Downloads config, registers service worker, sets up listeners.

await pwa.initialize(): Promise<InitializeResult>

Returns:

interface InitializeResult {
  success: boolean;
  error?: string;
  config?: PWAServiceConfig;
  deviceInfo?: DeviceInfo;
  installationState?: InstallationState;
}

downloadConfig()

Download service configuration from backend.

await pwa.downloadConfig(): Promise<PWAServiceConfig | null>

Push Notifications

registerForPush()

await pwa.registerForPush(options?: RegisterOptions): Promise<Registration | null>

Options:

Option	Type	Description
`userEmail`	string	User's email address
`userName`	string	User's display name
`userId`	string	Custom user identifier
`tags`	string[]	Tags for segmentation
`metadata`	object	Custom metadata

Returns:

interface Registration {
  id: string;
  registrationId: string;
  endpoint: string;
  deviceInfo: DeviceInfo;
}

unregisterFromPush()

Unregister from push notifications.

await pwa.unregisterFromPush(): Promise<boolean>

requestPermission()

Request notification permission from user.

await pwa.requestPermission(): Promise<NotificationPermission>
// Returns: 'granted' | 'denied' | 'default'

isRegistered()

Check if device is registered for push.

pwa.isRegistered(): boolean

getRegistrationId()

Get current registration ID.

pwa.getRegistrationId(): string | null

checkRegistrationStatus()

Check registration status from backend.

await pwa.checkRegistrationStatus(): Promise<RegistrationStatusResponse | null>

Installation

canInstall()

Check if PWA can be installed.

pwa.canInstall(): boolean

isInstalled()

Check if PWA is already installed.

pwa.isInstalled(): boolean

showInstallPrompt()

Show the PWA install prompt (Chrome/Edge).

await pwa.showInstallPrompt(): Promise<InstallResult>

Returns:

interface InstallResult {
  accepted: boolean;
  reason: 'accepted' | 'dismissed' | 'not-available' | 'already-installed' | 'ios-manual';
}

getInstallationState()

Get current installation state.

pwa.getInstallationState(): InstallationState
// Returns: 'not-installed' | 'prompt-available' | 'installing' | 'installed'

getInstallSteps()

Get installation steps for current platform (useful for iOS).

pwa.getInstallSteps(): string[]
// Returns: ['Tap the Share button', 'Select "Add to Home Screen"', ...]

Device Information

getDeviceInfo()

Get comprehensive device information (35+ fields).

pwa.getDeviceInfo(): DeviceInfo

Returns:

interface DeviceInfo {
  // OS
  os: string;              // 'iOS', 'Android', 'Windows', 'macOS', 'Linux'
  osVersion: string;       // '17.2', '14.0'
  
  // Device
  deviceType: string;      // 'iPhone', 'iPad', 'Phone', 'Tablet', 'Desktop'
  deviceModel: string;     // 'iPhone 15 Pro', 'Samsung Galaxy S24'
  isMobile: boolean;
  isTablet: boolean;
  isDesktop: boolean;
  
  // Browser
  browser: string;         // 'Chrome', 'Safari', 'Firefox', 'Edge'
  browserVersion: string;
  
  // PWA Capabilities
  supportLevel: 'full' | 'partial' | 'basic' | 'none';
  hasPushManager: boolean;
  hasServiceWorker: boolean;
  hasBadgeAPI: boolean;
  notificationPermission: 'granted' | 'denied' | 'default';
  
  // Screen
  screenWidth: number;
  screenHeight: number;
  devicePixelRatio: number;
  
  // Network
  isOnline: boolean;
  connectionType: string;  // '4g', '3g', 'wifi', 'unknown'
  
  // Identifiers
  browserFingerprint: string;
  // ... and more
}

getCapabilities()

Get PWA capability summary.

pwa.getCapabilities(): PWACapabilities

Heartbeat

startHeartbeat()

Start heartbeat for online status tracking.

pwa.startHeartbeat(): void

stopHeartbeat()

Stop heartbeat.

pwa.stopHeartbeat(): void

Badge

setBadge()

Set app badge count.

pwa.setBadge(count: number): void

clearBadge()

Clear app badge.

pwa.clearBadge(): void

Events

on()

Subscribe to an event.

pwa.on(event: PWAEvent, handler: (data) => void): void

off()

Unsubscribe from an event.

pwa.off(event: PWAEvent, handler: (data) => void): void

Available Events:

Event	Data	Description
`install:available`	`{ platforms }`	Install prompt available
`install:accepted`	`{ accepted }`	User accepted install
`install:dismissed`	`{ reason }`	User dismissed install
`install:completed`	`{}`	PWA installed
`push:registered`	`{ registrationId }`	Push registration successful
`push:unregistered`	`{}`	Push unregistered
`push:error`	`{ error }`	Push operation failed
`permission:denied`	`{ permission }`	Permission denied
`config:loaded`	`{ config }`	Config downloaded
`config:error`	`{ error }`	Config download failed
`heartbeat:sent`	`{ timestamp }`	Heartbeat sent
`heartbeat:error`	`{ error }`	Heartbeat failed
`network:online`	`{ isOnline }`	Network online
`network:offline`	`{ isOnline }`	Network offline
`sw:registered`	`{ registration }`	Service worker registered
`sw:updated`	`{ registration }`	Service worker updated

Utilities

getVersion()

Get SDK version.

pwa.getVersion(): string  // '1.0.0'

isInitialized()

Check if client is initialized.

pwa.isInitialized(): boolean

getServiceConfig()

Get downloaded service configuration.

pwa.getServiceConfig(): PWAServiceConfig | null

Browser Support

Browser	PWA Install	Push Notifications
Chrome 80+	✅	✅
Edge 80+	✅	✅
Firefox 78+	❌	✅
Safari 16.4+ (iOS)	Manual	✅
Safari 13+ (macOS)	❌	✅ (macOS 13+)
Samsung Internet 13+	✅	✅

On this page