Paul Bailey
7cda58440f
- Add self-hosted push notifications using VAPID (no external services) - Create PushSubscription model in database - Implement server-side push logic with web-push library - Add notification helpers for list events (items, invitations, collaborators) - Create NotificationSettings UI component for profile page - Add usePushNotifications React hook for subscription management - Create API routes for subscription management and VAPID key - Update service worker with push event handlers - Integrate notifications into item actions (add, remove, complete) - Integrate notifications into sharing actions (invite, accept, remove) - Add VAPID key generation script - Add comprehensive documentation and setup guides Notifications are sent when: - Items are added/removed/completed in shared lists - Users are invited to lists - Invitations are accepted - Collaborators are removed from lists Works on iOS 16.4+ (when installed to home screen), Android, and desktop browsers.
98 lines
2.4 KiB
Markdown
98 lines
2.4 KiB
Markdown
# Web Push Notifications Implementation Guide
|
|
|
|
## Overview
|
|
|
|
This guide explains how to implement Web Push notifications in your PWA using VAPID (self-hosted, no external service needed).
|
|
|
|
## Architecture
|
|
|
|
1. **VAPID Keys**: Generate once, store securely (like JWT secrets)
|
|
2. **Client**: Request permission, subscribe to push notifications
|
|
3. **Database**: Store push subscriptions per user
|
|
4. **Server**: Send notifications when list events occur
|
|
5. **Service Worker**: Receive and display notifications
|
|
|
|
## Setup Steps
|
|
|
|
### 1. Generate VAPID Keys
|
|
|
|
Run this once to generate your VAPID keys:
|
|
|
|
```bash
|
|
npx web-push generate-vapid-keys
|
|
```
|
|
|
|
Add to `.env`:
|
|
```
|
|
VAPID_PUBLIC_KEY=your_public_key_here
|
|
VAPID_PRIVATE_KEY=your_private_key_here
|
|
VAPID_SUBJECT=mailto:your-email@example.com
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
|
|
```bash
|
|
npm install web-push
|
|
```
|
|
|
|
### 3. Database Schema
|
|
|
|
Add `PushSubscription` model to store user subscriptions (see prisma/schema.prisma changes).
|
|
|
|
### 4. Client-Side Flow
|
|
|
|
1. User grants notification permission
|
|
2. Service worker subscribes to push manager
|
|
3. Subscription sent to server and stored in database
|
|
4. Server sends notifications when events occur
|
|
5. Service worker displays notifications
|
|
|
|
### 5. Notification Triggers
|
|
|
|
Notifications are sent when:
|
|
- Someone adds/removes an item from a shared list
|
|
- Someone invites you to a list
|
|
- Someone accepts your list invitation
|
|
- Someone removes you from a list
|
|
|
|
## Testing
|
|
|
|
### Local Testing
|
|
- Use Chrome DevTools > Application > Service Workers
|
|
- Use Chrome DevTools > Application > Push Messaging to simulate
|
|
|
|
### iOS Testing
|
|
- Must be installed to home screen
|
|
- iOS 16.4+ required
|
|
- Test on actual device (simulator doesn't support push)
|
|
|
|
### Android Testing
|
|
- Works in browser and installed PWA
|
|
- Test on actual device for best results
|
|
|
|
## Privacy & Best Practices
|
|
|
|
- Always request permission explicitly (don't auto-prompt)
|
|
- Allow users to disable notifications
|
|
- Store subscriptions securely
|
|
- Handle subscription expiration/updates
|
|
- Respect user preferences per list
|
|
|
|
## Troubleshooting
|
|
|
|
### Notifications not appearing
|
|
- Check permission status
|
|
- Verify service worker is active
|
|
- Check browser console for errors
|
|
- Ensure VAPID keys are correct
|
|
|
|
### iOS specific issues
|
|
- Must be installed to home screen
|
|
- Check iOS version (16.4+)
|
|
- Verify manifest.json is correct
|
|
|
|
### Subscription fails
|
|
- Check VAPID public key matches server
|
|
- Verify service worker scope
|
|
- Check network requests in DevTools
|