34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# Fix PWA Install Prompt Implementation Plan
|
|
|
|
## Objective
|
|
Ensure the PWA install prompt appears reliably on mobile devices, addressing potential issues with event timing, iOS compatibility, and explicit Service Worker registration.
|
|
|
|
## Root Causes to Address
|
|
1. **Late Event Listener**: The `beforeinstallprompt` event might fire before the React component mounts. We need to capture it globally as early as possible.
|
|
2. **Missing Service Worker Registration**: While `vite-plugin-pwa` can auto-inject, explicit registration in `main.tsx` ensures it's active and handles updates.
|
|
3. **iOS Compatibility**: iOS does not support `beforeinstallprompt`. We must detect iOS and show specific "Share -> Add to Home Screen" instructions.
|
|
4. **Secure Context**: PWA features require HTTPS. While we can't force this on the user's network, we can ensure the app behaves best-effort and maybe warn if needed (skipped for now to avoid noise, focusing on logical fixes).
|
|
|
|
## Tasks
|
|
1. **Update `src/client/src/main.tsx`**:
|
|
- Import `registerSW` from `virtual:pwa-register`.
|
|
- Add a global `window` event listener for `beforeinstallprompt` immediately upon script execution to capture the event.
|
|
- Expose the captured event on `window` (or a global store) so the React component can consume it.
|
|
2. **Update `src/client/src/components/PWAInstallPrompt.tsx`**:
|
|
- Check `window.deferredInstallPrompt` (or similar) on mount.
|
|
- Add User Agent detection for iOS (iPhone/iPad/iPod).
|
|
- If iOS, display a custom "Add to Home Screen" instruction banner.
|
|
- If Android/Desktop, use the captured prompt.
|
|
3. **Docs**: Update devlog.
|
|
|
|
## Technical Details
|
|
- **Global Property**: `window.deferredInstallPrompt`
|
|
- **iOS Detection**: Regex on `navigator.userAgent` looking for `iPhone|iPad|iPod` (and not `MSStream`).
|
|
|
|
## Status
|
|
- [x] Register SW explicitly in main.tsx
|
|
- [x] Capture `beforeinstallprompt` globally
|
|
- [x] Add iOS specific UI
|
|
- **Completed**: 2025-12-18
|
|
|