Skip to content

PWA_GUIDE.md

Latest commit

 

History

History
147 lines (107 loc) · 4.54 KB

PWA_GUIDE.md

File metadata and controls

147 lines (107 loc) · 4.54 KB
Raw

PWA (Progressive Web App) Installation Guide

Argus Dashboard can be installed as a Progressive Web App (PWA) on your devices, allowing you to:

  • Native App Experience: Access the dashboard like a native app without the browser UI
  • Offline Support: View cached data when offline (limited functionality)
  • Home Screen Shortcut: Add to your home screen for quick access
  • Installation on Multiple Platforms: Works on Windows, macOS, Linux, iOS, and Android

Installation Methods

Desktop (Windows/Mac/Linux)

  1. Open the Dashboard in a modern browser (Chrome, Edge, Firefox, Safari)

  2. Look for the Install Button - Either:

    • An "Install App" button in the header (if shown)
    • An install prompt from your browser (automatic on first visit)
    • Click the browser menu → "Install app" or similar option

  3. Confirm Installation - Click "Install" on the prompt

Mobile (iOS)

  1. Open Safari on your iPhone/iPad
  2. Navigate to your Argus Dashboard URL
  3. Tap the Share button (arrow icon)
  4. Scroll and select "Add to Home Screen"
  5. Name it "Argus Dashboard" and tap "Add"

Mobile (Android)

  1. Open Chrome (or other browser)
  2. Navigate to your Argus Dashboard URL
  3. Look for the install prompt (usually appears automatically)
  4. Tap "Install" or Menu → Install app
  5. The app will be added to your home screen

Features

Service Worker

  • Offline Caching: Static assets and recent API responses are cached
  • Auto-Updates: Service worker runs in background and checks for updates
  • Network-First APIs: API requests are fetched from network first, cached as fallback

Web App Manifest

  • App Metadata: Name, description, icons, colors
  • App Shortcuts: Quick access to dashboard
  • Screenshots: Shows what the app looks like

Features Enabled

  • 📱 Standalone mode (no browser UI)
  • 🎨 Custom theme colors
  • 🚀 Fast loading from cache
  • 📴 Offline support for cached content
  • 🎯 App shortcuts and home screen

Browser Support

OS Browser Support Notes
Windows Chrome/Edge ✅ Full All features
Windows Firefox ✅ Full All features
macOS Safari ✅ Limited Install via Share menu
macOS Chrome ✅ Full All features
iOS Safari ✅ Full Add to Home Screen
iOS Chrome ⚠️ Partial Limited by iOS
Android Chrome ✅ Full All features
Android Firefox ✅ Full All features

Uninstallation

Desktop

  • Right-click the app in your system app drawer/menu
  • Select "Uninstall" or equivalent

Mobile

  • Long-press the app icon on home screen
  • Select "Remove" or move to trash

Troubleshooting

Install Button Not Showing

  1. Browser Requirements: Ensure you're using a modern browser (Chrome 78+, Edge 79+, Firefox 76+, Safari 15.1+)
  2. HTTPS: PWA installation requires HTTPS (or localhost for development)
  3. Manifest: Browser must successfully load manifest.json
  4. Criteria: Service worker must be registered and manifest must be valid

Offline Features Not Working

  1. First Visit: The first visit caches assets - try refreshing
  2. Clear Cache: Browser → Settings → Clear site data
  3. Service Worker: Check browser DevTools → Application → Service Workers

HTTPS Warning

If you're getting warnings about installation:

  1. Ensure your domain uses HTTPS
  2. Check SSL certificate validity
  3. Allow mixed content if needed in development

Development

Service Worker Cache Strategy

Static Assets (JS, CSS, images):
- Cache first
- Updates from network in background

API Requests:
- Network first
- Falls back to cache if offline

Other:
- Network only

Adding PWA Features

To customize the PWA:

  1. Manifest: Edit /client/public/manifest.json

    • Change name, description, colors, icons

  2. Service Worker: Edit /client/public/sw.js

    • Modify caching strategy
    • Update cache version (CACHE_NAME)

  3. Install Button: Use useInstallPrompt() hook in any component

    const { isInstallable, install } = useInstallPrompt();

Performance Tips

  1. Regular Clear Cache: Periodically clear site data to free up space
  2. Update Service Worker: Changes are detected automatically
  3. Monitor Storage: Check DevTools for cache size
  4. Offline Behavior: API calls will fail gracefully if offline

Security Notes

  • PWA runs in same origin policy
  • No access to device system files
  • Permissions requested explicitly
  • HTTPS ensures data integrity