118 lines
3.6 KiB
Markdown
118 lines
3.6 KiB
Markdown
|
# PWA Implementation Guide
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
The Port Nimara Portal has been implemented as a Progressive Web App (PWA) to provide users with a native app-like experience on mobile devices.
|
||
|
|
|
||
|
|
## Features Implemented
|
||
|
|
|
||
|
|
### 1. PWA Configuration
|
||
|
|
- **App Name**: Port Nimara Portal
|
||
|
|
- **Short Name**: Port Nimara
|
||
|
|
- **Theme Color**: #387bca (brand primary color)
|
||
|
|
- **Background Color**: #ffffff
|
||
|
|
- **Display Mode**: standalone
|
||
|
|
- **Start URL**: /
|
||
|
|
- **Icons**: Multiple sizes from 72x72 to 512x512 pixels
|
||
|
|
|
||
|
|
### 2. Install Banner
|
||
|
|
- **Location**: Login page, below the login form
|
||
|
|
- **Behavior**:
|
||
|
|
- Only shows on mobile devices
|
||
|
|
- Hidden if app is already installed (standalone mode)
|
||
|
|
- Shows only once (dismissal stored in localStorage)
|
||
|
|
- Animated slide-in with 1-second delay
|
||
|
|
|
||
|
|
### 3. Installation Flow
|
||
|
|
- **Android**: Direct browser install prompt
|
||
|
|
- **iOS**: Step-by-step instructions modal
|
||
|
|
- **Other browsers**: Fallback instructions
|
||
|
|
|
||
|
|
### 4. Offline Support
|
||
|
|
- **Service Worker**: Auto-updating with Workbox
|
||
|
|
- **Caching**: Network-first for API calls, cache-first for assets
|
||
|
|
- **Navigation Fallback**: Routes to home page when offline
|
||
|
|
|
||
|
|
## Files Added/Modified
|
||
|
|
|
||
|
|
### New Files
|
||
|
|
- `components/PWAInstallBanner.vue` - Install banner component
|
||
|
|
- `composables/usePWA.ts` - PWA functionality composable
|
||
|
|
- `plugins/pwa.client.ts` - PWA initialization plugin
|
||
|
|
- `docs/pwa-implementation.md` - This documentation
|
||
|
|
|
||
|
|
### Modified Files
|
||
|
|
- `nuxt.config.ts` - Added PWA configuration
|
||
|
|
- `pages/login.vue` - Added install banner component
|
||
|
|
|
||
|
|
## Configuration Details
|
||
|
|
|
||
|
|
### PWA Module Settings
|
||
|
|
```typescript
|
||
|
|
pwa: {
|
||
|
|
registerType: 'autoUpdate',
|
||
|
|
manifest: {
|
||
|
|
name: 'Port Nimara Portal',
|
||
|
|
short_name: 'Port Nimara',
|
||
|
|
description: 'Port Nimara Client Portal - Manage your berth interests and expressions of interest',
|
||
|
|
theme_color: '#387bca',
|
||
|
|
background_color: '#ffffff',
|
||
|
|
display: 'standalone',
|
||
|
|
orientation: 'portrait',
|
||
|
|
start_url: '/',
|
||
|
|
scope: '/',
|
||
|
|
icons: [/* 8 icon sizes */]
|
||
|
|
},
|
||
|
|
workbox: {
|
||
|
|
// Caching strategies
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Icon Requirements
|
||
|
|
The following icon sizes are configured:
|
||
|
|
- 72x72, 96x96, 128x128, 144x144 (Android)
|
||
|
|
- 152x152, 192x192 (iOS, Android)
|
||
|
|
- 384x384, 512x512 (Splash screens, large displays)
|
||
|
|
|
||
|
|
All icons are located in `/public/icons/` and based on the circular Port Nimara logo.
|
||
|
|
|
||
|
|
### Browser Support
|
||
|
|
- **Chrome/Edge (Android)**: Full PWA support with install prompt
|
||
|
|
- **Safari (iOS)**: Manual installation via "Add to Home Screen"
|
||
|
|
- **Firefox**: Basic PWA support
|
||
|
|
- **Other browsers**: Graceful degradation with instructions
|
||
|
|
|
||
|
|
## Usage Instructions
|
||
|
|
|
||
|
|
### For Users
|
||
|
|
1. Visit the login page on a mobile device
|
||
|
|
2. If eligible, an install banner will appear below the login form
|
||
|
|
3. Tap "Install App" to begin installation
|
||
|
|
4. Follow platform-specific instructions if needed
|
||
|
|
|
||
|
|
### For Developers
|
||
|
|
The PWA functionality is automatically initialized. Use the `usePWA()` composable to access PWA state:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
const { isInstalled, canInstall, install, isMobile, isIOS } = usePWA();
|
||
|
|
```
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
- Test on actual mobile devices for best results
|
||
|
|
- Use Chrome DevTools > Application > Manifest to verify configuration
|
||
|
|
- Check Service Worker registration in DevTools > Application > Service Workers
|
||
|
|
- Test offline functionality by disabling network
|
||
|
|
|
||
|
|
## Deployment Notes
|
||
|
|
- Ensure HTTPS is enabled (required for PWA)
|
||
|
|
- Icons must be accessible via direct URLs
|
||
|
|
- Service worker will be auto-generated and registered
|
||
|
|
- Manifest will be auto-generated from nuxt.config.ts settings
|
||
|
|
|
||
|
|
## Future Enhancements
|
||
|
|
- Push notifications
|
||
|
|
- Background sync
|
||
|
|
- App shortcuts
|
||
|
|
- Share target functionality
|
||
|
|
- Install banner in dashboard for non-mobile users
|