`PWA_GUIDE.md`

473 lines
# Omega Watches PWA - Complete Guide

## Overview

The Omega Watches Progressive Web App (PWA) is a fully-featured mobile application with advanced capabilities including:

- **Offline Mode**: Full functionality without internet connection
- **Push Notifications**: Real-time price alerts and updates
- **Camera Scanner**: Identify watches by scanning reference numbers
- **Biometric Authentication**: Face ID, Touch ID, Fingerprint login
- **AR Try-On**: Virtual watch try-on using augmented reality
- **Add to Home Screen**: Install as native app on mobile devices
- **Background Sync**: Auto-sync data when connection is restored
- **Responsive Design**: Optimized for all screen sizes

## Features

### 1. Service Worker & Offline Support

The PWA uses an advanced service worker (`sw-advanced.js`) that provides:

- **Multiple caching strategies**:
  - Cache-first for static assets (instant loading)
  - Network-first for API calls (fresh data)
  - Stale-while-revalidate for images

- **Smart caching**:
  - Critical assets cached on install
  - API responses cached for offline access
  - Images cached on-demand
  - AR models cached for offline viewing

- **Cache management**:
  - Automatic cleanup of old caches
  - Version-based cache control
  - Manual cache clearing option

### 2. Push Notifications

Real-time notifications powered by Web Push API:

**Setup Required**:
```bash
# Generate VAPID keys
npm install -g web-push
web-push generate-vapid-keys

# Add to .env file
VAPID_PUBLIC_KEY=your_public_key
VAPID_PRIVATE_KEY=your_private_key
VAPID_SUBJECT=mailto:admin@omegawatches.example.com
```

**Notification Types**:
- Price alerts (significant price changes)
- New watch additions
- Trending watches
- Custom notifications

**Usage**:
```javascript
// Subscribe to notifications
await window.pwaApp.requestNotificationPermission();

// Send test notification
await fetch('/api/pwa/send-notification', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Test',
    body: 'This is a test notification'
  })
});
```

### 3. Camera Scanner

Identify watches by scanning reference numbers or barcodes:

**Features**:
- Live camera feed with overlay
- Auto-focus and torch/flashlight support
- Front/back camera switching
- Capture and save scans
- Scan history with IndexedDB storage

**Usage**:
```javascript
// Initialize scanner
const scanner = await window.pwaApp.initScanner();
await scanner.start();

// Capture image
const imageData = scanner.captureFrame();

// Switch camera
await scanner.switchCamera();

// Toggle flashlight
await scanner.toggleTorch();
```

**Production Enhancement**:
For production, integrate:
- Tesseract.js for OCR (text recognition)
- ZXing for barcode scanning
- Google Cloud Vision API for better accuracy

### 4. Biometric Authentication

Secure authentication using Web Authentication API (WebAuthn):

**Supported Methods**:
- Face ID (iOS/macOS)
- Touch ID (iOS/macOS)
- Fingerprint (Android)
- Windows Hello (Windows)
- Platform authenticators

**Features**:
- Register biometric credentials
- Quick authentication
- Credential management
- Auto-detect auth type

**Usage**:
```javascript
// Check availability
const available = await window.pwaApp.biometricAuth.isAvailable;

// Register
const result = await window.pwaApp.biometricAuth.register(
  'username',
  'Display Name'
);

// Authenticate
const auth = await window.pwaApp.biometricAuth.authenticate('username');

// Quick auth (last user)
const quickAuth = await window.pwaApp.biometricAuth.quickAuth();
```

### 5. AR Try-On

Virtual watch try-on using device camera:

**Features**:
- Live camera feed
- Real-time watch rendering
- Manual positioning mode
- Screenshot capture
- Multiple watch models

**Usage**:
```javascript
// Initialize AR viewer
const ar = await window.pwaApp.initAR();

// Start AR session
await ar.start('watch-id');

// Take screenshot
const screenshot = await ar.takeScreenshot();

// Manual positioning
ar.enableManualMode();
ar.updatePosition(x, y, rotation);

// Stop session
ar.stop();
```

**Production Enhancement**:
- Integrate TensorFlow.js for hand tracking
- Use MediaPipe for better accuracy
- Add 3D GLTF/GLB watch models
- Implement WebXR for immersive AR

### 6. IndexedDB Storage

Offline data storage using IndexedDB:

**Object Stores**:
- `watches` - Cached watch data
- `pendingActions` - Actions queued for sync
- `scannedWatches` - Camera scan history
- `arScreenshots` - AR try-on screenshots
- `biometric` - Biometric credentials
- `preferences` - User preferences

**Auto-sync**:
Background sync automatically uploads pending data when online.

## Installation

### 1. Install Dependencies

```bash
cd /root/Projects/watches
npm install
```

This will install:
- `web-push` for push notifications
- All existing dependencies

### 2. Configure Environment

Create or update `.env` file:

```bash
# Generate VAPID keys first
npx web-push generate-vapid-keys

# Add to .env
VAPID_PUBLIC_KEY=your_generated_public_key
VAPID_PRIVATE_KEY=your_generated_private_key
VAPID_SUBJECT=mailto:your-email@example.com
```

### 3. Update Server

Add PWA routes to your server:

```javascript
// In server.js
import pwaRoutes from './pwa-routes.js';

// Add before other routes
app.use('/api/pwa', pwaRoutes);
```

### 4. Start Server

```bash
# Development
npm start

# Production with PM2
pm2 start server.js --name omega-watches-pwa
```

### 5. Access PWA

Navigate to:
```
http://45.61.58.125:7600/pwa-index.html
```

## App Store Deployment

### iOS App Store (via PWA Builder)

1. **Test on iOS**:
   - Open Safari on iPhone/iPad
   - Navigate to your PWA
   - Tap Share > Add to Home Screen

2. **Submit to App Store**:
   - Use [PWABuilder.com](https://www.pwabuilder.com/)
   - Enter your PWA URL
   - Download iOS package
   - Submit via Xcode

**Requirements**:
- Valid manifest.json ✓
- Service worker ✓
- HTTPS in production ✓
- Icons (all sizes) ✓
- Screenshots ✓

### Google Play Store (via Trusted Web Activity)

1. **Test on Android**:
   - Open Chrome on Android
   - Navigate to your PWA
   - Tap menu > Add to Home Screen

2. **Submit to Play Store**:
   - Use [Bubblewrap](https://github.com/GoogleChromeLabs/bubblewrap)
   - Or use [PWABuilder.com](https://www.pwabuilder.com/)
   - Sign APK/AAB with your keystore
   - Upload to Play Console

**Requirements**:
- Valid manifest.json ✓
- Service worker ✓
- TWA validation ✓
- Digital Asset Links ✓

### Microsoft Store (via PWA)

1. **Submit**:
   - Use [PWABuilder.com](https://www.pwabuilder.com/)
   - Generate Windows package
   - Submit to Microsoft Partner Center

## Testing

### Test Offline Mode

```javascript
// In DevTools Console
// Go offline
// Navigate the app - should work offline
// Go online - data should sync
```

### Test Push Notifications

```bash
# Send test notification
curl -X POST http://45.61.58.125:7600/api/pwa/send-notification \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Alert",
    "body": "This is a test notification"
  }'
```

### Test Camera Scanner

1. Open Scanner view
2. Allow camera permission
3. Point at text/barcode
4. Capture image

### Test Biometric Auth

1. Click biometric login button
2. Follow device prompts
3. Verify authentication

### Test AR Try-On

1. Open AR view
2. Select watch model
3. Position wrist in camera
4. Take screenshot

## Performance

### Lighthouse Scores (Target)

- Performance: 90+
- PWA: 100
- Accessibility: 95+
- Best Practices: 95+
- SEO: 95+

### Bundle Sizes

- Service Worker: ~15KB
- PWA App: ~25KB
- Camera Scanner: ~8KB
- Biometric Auth: ~6KB
- AR Viewer: ~12KB

**Total PWA overhead**: ~66KB (gzipped: ~20KB)

## Browser Support

| Feature | Chrome | Safari | Firefox | Edge |
|---------|--------|--------|---------|------|
| Service Worker | ✓ | ✓ | ✓ | ✓ |
| Push Notifications | ✓ | ✓ (16+) | ✓ | ✓ |
| Web Share | ✓ | ✓ | ✓ | ✓ |
| Camera API | ✓ | ✓ | ✓ | ✓ |
| WebAuthn | ✓ | ✓ | ✓ | ✓ |
| IndexedDB | ✓ | ✓ | ✓ | ✓ |
| Background Sync | ✓ | - | - | ✓ |
| Periodic Sync | ✓ | - | - | ✓ |

## API Endpoints

### Push Notifications

```
GET  /api/pwa/vapid-public-key     - Get VAPID public key
POST /api/pwa/subscribe            - Subscribe to push
POST /api/pwa/unsubscribe          - Unsubscribe from push
POST /api/pwa/send-notification    - Send notification
POST /api/pwa/price-alert          - Send price alert
GET  /api/pwa/subscription-stats   - Get subscription stats
```

### Sync

```
POST /api/pwa/sync-watchlist       - Sync watchlist
POST /api/pwa/sync-favorites       - Sync favorites
POST /api/pwa/scan-result          - Save scan result
POST /api/pwa/ar-screenshot        - Save AR screenshot
```

### Info

```
GET  /api/pwa/app-info             - Get app info
POST /share                        - Web Share Target
```

## Troubleshooting

### Service Worker Not Registering

1. Check HTTPS (required in production)
2. Verify `sw-advanced.js` is accessible
3. Check console for errors
4. Try unregistering old workers

### Push Notifications Not Working

1. Verify VAPID keys are set
2. Check notification permission
3. Ensure HTTPS in production
4. Test with different browsers

### Camera Not Accessible

1. Check camera permissions
2. Ensure HTTPS in production
3. Try different browsers
4. Check device compatibility

### Biometric Auth Failing

1. Verify WebAuthn support
2. Check platform authenticator
3. Ensure HTTPS in production
4. Try different auth methods

## Security

- HTTPS required in production
- Content Security Policy configured
- VAPID keys for push auth
- Biometric data encrypted
- No sensitive data in cache
- Regular security audits

## Best Practices

1. **Always use HTTPS in production**
2. **Cache wisely** - don't cache sensitive data
3. **Test offline mode** thoroughly
4. **Request permissions** only when needed
5. **Provide fallbacks** for unsupported features
6. **Monitor cache sizes** - implement cleanup
7. **Version your caches** for easy updates
8. **Test on real devices** not just emulators

## Support

For issues or questions:
- Check console for errors
- Review service worker logs
- Test in different browsers
- Check device compatibility
- Verify HTTPS in production

## Future Enhancements

- [ ] WebXR for immersive AR
- [ ] TensorFlow.js hand tracking
- [ ] Offline ML for watch recognition
- [ ] P2P sync with WebRTC
- [ ] Voice commands
- [ ] Apple Watch companion
- [ ] Wear OS support
- [ ] Desktop PWA features