PWA SDK client

Client-side SDK for PWA features including push notifications, install prompts, and device detection.

The CloudSignal PWA SDK enables push notifications, PWA installation prompts, and comprehensive device tracking in your web applications.

This SDK is the client-side counterpart to the Push Notifications API. Use this SDK in your frontend; use the API to send notifications from your backend.

Features

Feature	What it does
Push notifications	Web Push with VAPID authentication
PWA installation	Automatic install prompt handling with iOS manual instructions
Device detection	35+ device/browser/OS detection fields
Heartbeat	Real-time online status tracking
Service worker	Badge management, notification history, offline support

Installation

npm install @cloudsignal/pwa-sdk

yarn add @cloudsignal/pwa-sdk

<script src="https://unpkg.com/@cloudsignal/pwa-sdk/dist/index.global.js"></script>

Quick start

Get your credentials

Go to Dashboard → Extensions → Push Notifications
Enable the extension if not already enabled
Copy your Organization ID, Secret, and Service ID

Add web app manifest

Create public/manifest.json:

{
  "name": "Your App Name",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Add to HTML: <link rel="manifest" href="/manifest.json">

Copy service worker

cp node_modules/@cloudsignal/pwa-sdk/dist/service-worker.js public/

Initialize SDK

import { CloudSignalPWA } from '@cloudsignal/pwa-sdk';

const pwa = new CloudSignalPWA({
  organizationId: 'your-org-uuid',
  organizationPublishableKey: 'pk_your_publishable_key',
  serviceId: 'your-service-uuid',
  debug: true
});

await pwa.initialize();

Register for push

const registration = await pwa.registerForPush({
  userEmail: 'user@example.com'
});

if (registration) {
  console.log('Registered:', registration.id);
}

Complete example

import { CloudSignalPWA } from '@cloudsignal/pwa-sdk';

const pwa = new CloudSignalPWA({
  organizationId: 'your-org-uuid',
  organizationPublishableKey: 'pk_your_publishable_key',
  serviceId: 'your-service-uuid',
  debug: true
});

// Event listeners
pwa.on('install:available', () => console.log('PWA can be installed'));
pwa.on('push:registered', (data) => console.log('Registered:', data.registrationId));
pwa.on('permission:denied', () => console.log('Permission denied'));

// Initialize
const result = await pwa.initialize();
console.log('Device:', result.deviceInfo?.deviceModel);

// Show install prompt if available
if (pwa.canInstall()) {
  const installResult = await pwa.showInstallPrompt();
  console.log('Installed:', installResult.accepted);
}

// Register for push notifications
const registration = await pwa.registerForPush({
  userEmail: 'user@example.com',
  userName: 'John Doe',
  tags: ['premium-user']
});

// Start heartbeat for online status
pwa.startHeartbeat();

CDN usage

<!DOCTYPE html>
<html>
<head>
  <link rel="manifest" href="/manifest.json">
</head>
<body>
  <button id="enable-push">Enable Notifications</button>

  <script src="https://unpkg.com/@cloudsignal/pwa-sdk/dist/index.global.js"></script>
  <script>
    const pwa = new CloudSignalPWA.CloudSignalPWA({
      organizationId: 'your-org-uuid',
      organizationPublishableKey: 'pk_your_publishable_key',
      serviceId: 'your-service-uuid'
    });

    pwa.initialize();

    document.getElementById('enable-push').onclick = async () => {
      const reg = await pwa.registerForPush({ userEmail: 'user@example.com' });
      if (reg) alert('Notifications enabled!');
    };
  </script>
</body>
</html>

API reference

Constructor

new CloudSignalPWA(config: PWAConfig)

Option	Type	Required	Description
`organizationId`	string	Yes	Your 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

Methods

Initialization

await pwa.initialize()        // Initialize SDK
await pwa.downloadConfig()    // Download service config

Push notifications

await pwa.registerForPush({ userEmail, userName, tags, metadata })
await pwa.unregisterFromPush()
await pwa.requestPermission()
pwa.isRegistered()
pwa.getRegistrationId()

Installation

pwa.canInstall()              // Check if installable
pwa.isInstalled()             // Check if already installed
await pwa.showInstallPrompt() // Show install prompt
pwa.getInstallSteps()         // Get iOS manual steps

Device info

pwa.getDeviceInfo()           // Get 35+ device fields
pwa.getCapabilities()         // Get PWA capabilities

Heartbeat

pwa.startHeartbeat()          // Start online status tracking
pwa.stopHeartbeat()           // Stop heartbeat

Badge

pwa.setBadge(count)           // Set app badge count
pwa.clearBadge()              // Clear badge

Events

pwa.on(event, handler)
pwa.off(event, handler)

Event	Description
`install:available`	Install prompt available
`install:completed`	PWA installed
`push:registered`	Push registration successful
`push:unregistered`	Push unregistered
`push:error`	Push operation failed
`permission:denied`	Permission denied
`heartbeat:sent`	Heartbeat sent
`network:online`	Network online
`network:offline`	Network offline
`sw:registered`	Service worker registered
`sw:updated`	Service worker updated

Device information

The SDK detects 35+ device attributes:

const info = pwa.getDeviceInfo();

info.os              // 'iOS', 'Android', 'Windows', 'macOS'
info.osVersion       // '17.2', '14.0'
info.deviceType      // 'iPhone', 'Phone', 'Tablet', 'Desktop'
info.deviceModel     // 'iPhone 15 Pro', 'Samsung Galaxy S24'
info.browser         // 'Chrome', 'Safari', 'Firefox'
info.browserVersion  // '120.0'
info.supportLevel    // 'full', 'partial', 'basic', 'none'
info.hasPushManager  // true/false
info.hasServiceWorker // true/false
info.isOnline        // true/false
info.connectionType  // '4g', '3g', 'wifi'

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+	✅	✅

Next steps

Push notifications API - Send notifications from backend
Extension settings - Configure VAPID keys and options

On this page