mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
5f27abddd4
* feat(web): in-app PWA update prompt when new service worker is available (closes #938) User-controlled reload with a persistent banner, visibility-triggered SW checks, and an expandable rationale. Switches registerType to prompt. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): align vite.config with soup layers for clean driver merge Keeps registerType prompt while matching garden IWER stubs and PWA share_target shape expected by feat/pwa-share-target in the manifest. Co-authored-by: Cursor <cursoragent@cursor.com> * Revert "fix(web): align vite.config with soup layers for clean driver merge" This reverts commit 6f0915b0884d029a2413d8819a4dfe81d7c4e595. * fix(web): make PWA reload apply waiting service worker updates Handle SKIP_WAITING in injectManifest sw.ts and reload via controllerchange with a timed fallback when vite-plugin-pwa prompt mode does not navigate. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): satisfy setTimeout mock typing in PWA reload tests Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): register PWA service worker before auth gates Mount PwaUpdateProvider at app root and show the update banner on login and error screens so registerSW runs for logged-out users too. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): offset PWA update banner below top status banners Reserve top-12 when syncing or reconnecting so the reload prompt stays visible above SyncingBanner and ReconnectingBanner. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): offset PWA update banner below voice error banner Use PwaUpdateBannerWithStatusOffset inside VoiceProvider so voice errors share the same top-12 reservation as sync and reconnect banners. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
204 lines
5.2 KiB
Markdown
204 lines
5.2 KiB
Markdown
# 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)
|
|
|
|
1. Open HAPI in Chrome or Edge browser
|
|
2. Look for the **"Install HAPI"** banner at the bottom
|
|
3. Tap **"Install"**
|
|
4. 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)
|
|
|
|
1. Open HAPI in Safari browser
|
|
2. Tap the **Share** button (square with arrow)
|
|
3. Scroll down and tap **"Add to Home Screen"**
|
|
4. 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)
|
|
|
|
1. Open HAPI in your browser
|
|
2. Click the install icon in the address bar (⊕)
|
|
3. Or use the menu: **"Install HAPI..."**
|
|
4. 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 checks for updates in the background and lets you choose when to reload:
|
|
|
|
- Updates are checked hourly and when you return to the tab
|
|
- When a new version is available, a persistent in-app banner appears at the top
|
|
- Tap **Reload** when you're ready to apply the update — the banner stays until you do
|
|
- Expand **"Why can't I dismiss this?"** on the banner for the rationale
|
|
|
|
HAPI uses a user-controlled reload instead of forcing an automatic refresh, so you choose when to reload. The banner cannot be dismissed without upgrading, so you won't forget you're on an old build.
|
|
|
|
### 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
|
|
|
|
HAPI supports push notifications to alert you when agents need attention.
|
|
|
|
### Enable Notifications
|
|
|
|
1. Open HAPI - a permission popup appears automatically
|
|
2. Tap **Allow** to enable notifications
|
|
3. If you missed the popup, go to system settings to grant permission
|
|
|
|
### Notification Types
|
|
|
|
| Type | When Sent |
|
|
|------|-----------|
|
|
| Permission Request | Agent needs your approval |
|
|
| Ready | Agent finished and awaits input |
|
|
|
|
::: tip
|
|
If push notifications don't work in your region (e.g., FCM unavailable), use [Telegram integration](./installation.md#telegram-setup) instead.
|
|
:::
|
|
|
|
## 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:**
|
|
1. Long-press the HAPI icon
|
|
2. Drag to "Uninstall" or tap the X
|
|
|
|
**iOS:**
|
|
1. Long-press the HAPI icon
|
|
2. Tap "Remove App" → "Delete App"
|
|
|
|
**Desktop:**
|
|
1. Open HAPI
|
|
2. Click the three-dot menu
|
|
3. Select "Uninstall HAPI"
|
|
|
|
### Clearing Cache
|
|
|
|
If you experience issues:
|
|
|
|
1. Open HAPI in browser (not installed version)
|
|
2. Open Developer Tools (F12)
|
|
3. Go to Application → Storage
|
|
4. 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
|
|
|
|
1. Close the app completely
|
|
2. Reopen and wait for update prompt
|
|
3. 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](./installation.md#telegram-setup) for Telegram setup.
|