weishu
460c393006
- Initialize VitePress documentation site with config, index, and guides - Add guides for quick-start, installation, PWA, how-it-works, FAQ, and why HAPI - Update .gitignore to exclude VitePress cache directory - Update logo.svg with actual icon from web/public/icon.svg - Simplify README.md with link to full installation guide - Remove redundant WHY_NOT_HAPPY.md (content migrated to why-hapi guide)
4.4 KiB
Progressive Web App (PWA)
HAPI's web interface is a fully-featured PWA that can be installed on your phone for a native app-like experience.
What is PWA?
A Progressive Web App (PWA) is a web application that can be installed on your device and works like a native app:
- Home screen icon - Launch HAPI like any other app
- Full screen mode - No browser chrome, immersive experience
- Offline support - Basic functionality works without internet
- Auto-updates - Always get the latest version
Installing HAPI PWA
Android (Chrome/Edge)
- Open HAPI in Chrome or Edge browser
- Look for the "Install HAPI" banner at the bottom
- Tap "Install"
- HAPI appears on your home screen
::: tip If you don't see the install banner, tap the three-dot menu and select "Add to Home screen" or "Install app". :::
iOS (Safari)
- Open HAPI in Safari browser
- Tap the Share button (square with arrow)
- Scroll down and tap "Add to Home Screen"
- Tap "Add" in the top right corner
::: warning iOS requires Safari for PWA installation. Chrome/Firefox on iOS don't support the "Add to Home Screen" feature. :::
Desktop (Chrome/Edge)
- Open HAPI in your browser
- Click the install icon in the address bar (⊕)
- Or use the menu: "Install HAPI..."
- HAPI opens as a standalone window
PWA Features
Offline Mode
When offline, HAPI can:
- Display cached session lists
- Show previously loaded messages
- Queue actions for when you're back online
An offline indicator appears when you lose connection.
Auto-Update
HAPI automatically checks for updates:
- Updates are checked hourly in the background
- When a new version is available, you'll see a prompt
- Click "Reload" to get the latest version
Background Sync
Actions taken offline are synced when reconnected:
- Pending messages are sent
- Permission decisions are relayed
- Session state is refreshed
Caching Strategy
HAPI uses intelligent caching:
| Content | Strategy | Duration |
|---|---|---|
| App shell | Cache first | Until update |
| Sessions API | Network first | 5 minutes |
| Machines API | Network first | 10 minutes |
| Static assets | Cache first | Forever |
Notifications
::: warning Work in Progress Push notifications are planned for a future release. Currently, notifications work through:
- Telegram bot (recommended)
- Keeping the app open in background :::
Managing Your PWA
Check Install Status
HAPI shows different UI based on install status:
- Not installed - Shows install prompt
- Installing - Shows progress indicator
- Installed - No prompt shown
Uninstalling
Android:
- Long-press the HAPI icon
- Drag to "Uninstall" or tap the X
iOS:
- Long-press the HAPI icon
- Tap "Remove App" → "Delete App"
Desktop:
- Open HAPI
- Click the three-dot menu
- Select "Uninstall HAPI"
Clearing Cache
If you experience issues:
- Open HAPI in browser (not installed version)
- Open Developer Tools (F12)
- Go to Application → Storage
- Click "Clear site data"
Best Practices
Battery Optimization
On Android, disable battery optimization for HAPI to ensure:
- Background sync works reliably
- Notifications arrive promptly
Settings → Apps → HAPI → Battery → Unrestricted
Data Usage
HAPI uses minimal data:
- Initial load: ~500KB
- Cached after first load
- Only syncs changed data
Multiple Devices
You can install HAPI on multiple devices:
- All devices use the same server
- Sessions sync across devices
- Same access token works everywhere
Troubleshooting
Install Button Not Showing
- Ensure you're using HTTPS (required for PWA)
- Try refreshing the page
- Check if already installed
App Not Updating
- Close the app completely
- Reopen and wait for update prompt
- If stuck, clear cache and reinstall
Offline Mode Not Working
- Ensure you've loaded the app at least once online
- Check if ServiceWorker is registered (DevTools → Application)
- Clear cache and reload
iOS-Specific Issues
- Must use Safari for installation
- No background sync on iOS
- Limited offline capabilities
Telegram Mini App Alternative
If PWA doesn't suit your needs, consider the Telegram Mini App:
- Works inside Telegram
- No separate installation
- Same features as PWA
- Integrated notifications
See Installation Guide for Telegram setup.