feat: integrate daily notification plugin for native iOS/Android
Add native notification support via @timesafari/daily-notification-plugin while maintaining existing Web Push for web/PWA builds. Platform detection automatically selects the appropriate notification system at runtime. Key Changes: - Created NotificationService abstraction layer with unified API - Implemented NativeNotificationService for iOS/Android - Stubbed WebPushNotificationService for future web integration - Registered DailyNotificationPlugin in Capacitor plugin system Android Configuration: - Added notification permissions (POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM, etc.) - Registered DailyNotificationReceiver for alarm-based notifications - Registered BootReceiver to restore schedules after device restart - Added Room, WorkManager, and Coroutines dependencies - Registered plugin in MainActivity.java iOS Configuration: - Added UIBackgroundModes (fetch, processing) to Info.plist - Configured BGTaskSchedulerPermittedIdentifiers - Added NSUserNotificationAlertStyle Documentation: - Created comprehensive integration guide - Added architecture overview with diagrams - Created implementation checklist - Documented platform-specific behavior Manual Steps Required: - iOS: Enable Background Modes capability in Xcode - iOS: Run `pod install` to install CapacitorDailyNotification pod - Run `npx cap sync` to sync native projects Platform Support: - iOS: Native UNUserNotificationCenter (requires Xcode setup) - Android: Native NotificationManager with AlarmManager - Web/PWA: Existing Web Push (coexists, not yet wired to service) - Electron: Ready (uses native implementation) Status: Phase 1 complete - infrastructure ready for UI integration Next: Update PushNotificationPermission.vue to use NotificationService
This commit is contained in:
Jose Olarte III
237
doc/daily-notification-plugin-integration.md
Normal file
237
doc/daily-notification-plugin-integration.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Daily Notification Plugin Integration
|
||||
|
||||
**Date**: 2026-01-21
|
||||
**Status**: ✅ Phase 1 Complete - Native Infrastructure
|
||||
**Integration Type**: Native + Web Coexistence
|
||||
|
||||
## Overview
|
||||
|
||||
The Daily Notification Plugin has been integrated to provide native notification functionality for iOS and Android while maintaining existing Web Push for web/PWA builds. The integration uses platform detection to automatically select the appropriate notification system at runtime.
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
### 1. **Plugin Registration** ✅
|
||||
- **File**: `src/plugins/DailyNotificationPlugin.ts`
|
||||
- Registered Capacitor plugin with proper TypeScript types
|
||||
- Native-only (no web implementation)
|
||||
|
||||
### 2. **Service Abstraction Layer** ✅
|
||||
Created unified notification service with platform-specific implementations:
|
||||
|
||||
- **`NotificationService.ts`**: Factory that selects implementation based on platform
|
||||
- **`NativeNotificationService.ts`**: Wraps DailyNotificationPlugin for iOS/Android
|
||||
- **`WebPushNotificationService.ts`**: Stub for future Web Push integration
|
||||
|
||||
**Location**: `src/services/notifications/`
|
||||
|
||||
**Key Features**:
|
||||
- Unified interface (`NotificationServiceInterface`)
|
||||
- Automatic platform detection via `Capacitor.isNativePlatform()`
|
||||
- Type-safe implementation
|
||||
- Singleton pattern for efficiency
|
||||
|
||||
### 3. **Android Configuration** ✅
|
||||
|
||||
**Modified Files**:
|
||||
- `android/app/src/main/AndroidManifest.xml`
|
||||
- `android/app/build.gradle`
|
||||
- `android/app/src/main/java/app/timesafari/MainActivity.java`
|
||||
|
||||
**Changes**:
|
||||
- ✅ Added notification permissions (POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM, etc.)
|
||||
- ✅ Registered `DailyNotificationReceiver` (critical for alarm delivery)
|
||||
- ✅ Registered `BootReceiver` (restores schedules after device restart)
|
||||
- ✅ Added Room, WorkManager, and Coroutines dependencies
|
||||
- ✅ Registered plugin in MainActivity
|
||||
|
||||
### 4. **iOS Configuration** ✅
|
||||
|
||||
**Modified Files**:
|
||||
- `ios/App/App/Info.plist`
|
||||
|
||||
**Changes**:
|
||||
- ✅ Added `UIBackgroundModes` (fetch, processing)
|
||||
- ✅ Added `BGTaskSchedulerPermittedIdentifiers` for background tasks
|
||||
- ✅ Added `NSUserNotificationAlertStyle` for alert-style notifications
|
||||
|
||||
**Still Required** (Manual in Xcode):
|
||||
- ⚠️ Enable "Background Modes" capability in Xcode
|
||||
- Background fetch
|
||||
- Background processing
|
||||
- ⚠️ Enable "Push Notifications" capability (if using remote notifications)
|
||||
|
||||
## Platform Behavior
|
||||
|
||||
| Platform | Implementation | Status |
|
||||
|----------|---------------|--------|
|
||||
| **iOS** | DailyNotificationPlugin (native) | ✅ Configured |
|
||||
| **Android** | DailyNotificationPlugin (native) | ✅ Configured |
|
||||
| **Web/PWA** | Web Push (existing) | 🔄 Not yet wired up |
|
||||
| **Electron** | Would use native | ✅ Ready |
|
||||
|
||||
## Usage Example
|
||||
|
||||
```typescript
|
||||
import { NotificationService } from '@/services/notifications/NotificationService';
|
||||
|
||||
// Get the appropriate service for current platform
|
||||
const notificationService = NotificationService.getInstance();
|
||||
|
||||
// Check platform
|
||||
console.log('Platform:', NotificationService.getPlatform());
|
||||
console.log('Is native:', NotificationService.isNative());
|
||||
|
||||
// Request permissions
|
||||
const granted = await notificationService.requestPermissions();
|
||||
|
||||
if (granted) {
|
||||
// Schedule daily notification
|
||||
await notificationService.scheduleDailyNotification({
|
||||
time: '09:00',
|
||||
title: 'Daily Check-In',
|
||||
body: 'Time to check your TimeSafari activity',
|
||||
priority: 'normal'
|
||||
});
|
||||
}
|
||||
|
||||
// Check status
|
||||
const status = await notificationService.getStatus();
|
||||
console.log('Enabled:', status.enabled);
|
||||
console.log('Time:', status.scheduledTime);
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Phase 2: UI Integration
|
||||
- [ ] Update `PushNotificationPermission.vue` to use `NotificationService`
|
||||
- [ ] Add platform-aware UI messaging
|
||||
- [ ] Update settings storage to work with both systems
|
||||
- [ ] Test notification scheduling UI
|
||||
|
||||
### Phase 3: Web Push Integration
|
||||
- [ ] Wire `WebPushNotificationService` to existing PushNotificationPermission logic
|
||||
- [ ] Extract web push subscription code into service methods
|
||||
- [ ] Test web platform notification flow
|
||||
|
||||
### Phase 4: Testing & Polish
|
||||
- [ ] Test on real iOS device
|
||||
- [ ] Test on real Android device (API 23+, API 33+)
|
||||
- [ ] Test permission flows
|
||||
- [ ] Test notification delivery
|
||||
- [ ] Test app restart/reboot scenarios
|
||||
- [ ] Verify background notification delivery
|
||||
|
||||
### Phase 5: Xcode Configuration (iOS Only)
|
||||
- [ ] Open `ios/App/App.xcodeproj` in Xcode
|
||||
- [ ] Select App target → Signing & Capabilities
|
||||
- [ ] Click "+ Capability" → Add "Background Modes"
|
||||
- Enable "Background fetch"
|
||||
- Enable "Background processing"
|
||||
- [ ] Click "+ Capability" → Add "Push Notifications" (if using remote)
|
||||
- [ ] Run `pod install` in `ios/` directory
|
||||
- [ ] Build and test on device
|
||||
|
||||
## Build Commands
|
||||
|
||||
### Sync Capacitor
|
||||
```bash
|
||||
npx cap sync
|
||||
# or
|
||||
npx cap sync android
|
||||
npx cap sync ios
|
||||
```
|
||||
|
||||
### Build Android
|
||||
```bash
|
||||
npm run build:android
|
||||
# or
|
||||
npm run build:android:debug
|
||||
```
|
||||
|
||||
### Build iOS
|
||||
```bash
|
||||
npm run build:ios
|
||||
# or after Xcode setup:
|
||||
cd ios && pod install && cd ..
|
||||
npm run build:ios:debug
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Android
|
||||
- **Critical**: `DailyNotificationReceiver` must be in AndroidManifest.xml
|
||||
- Android 12+ (API 31+) requires `SCHEDULE_EXACT_ALARM` permission
|
||||
- Android 13+ (API 33+) requires runtime `POST_NOTIFICATIONS` permission
|
||||
- BootReceiver restores schedules after device restart
|
||||
|
||||
### iOS
|
||||
- **Critical**: Background modes must be enabled in Xcode capabilities
|
||||
- iOS 13.0+ supported (already compatible with your deployment target)
|
||||
- Background tasks use `BGTaskScheduler`
|
||||
- User must grant notification permissions in Settings
|
||||
|
||||
### Web
|
||||
- Existing Web Push continues to work
|
||||
- No conflicts with native implementation
|
||||
- Platform detection ensures correct system is used
|
||||
|
||||
## Files Modified
|
||||
|
||||
### Created
|
||||
- `src/plugins/DailyNotificationPlugin.ts`
|
||||
- `src/services/notifications/NotificationService.ts`
|
||||
- `src/services/notifications/NativeNotificationService.ts`
|
||||
- `src/services/notifications/WebPushNotificationService.ts`
|
||||
|
||||
### Modified
|
||||
- `android/app/src/main/AndroidManifest.xml`
|
||||
- `android/app/build.gradle`
|
||||
- `android/app/src/main/java/app/timesafari/MainActivity.java`
|
||||
- `ios/App/App/Info.plist`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Android: Notifications Not Appearing
|
||||
1. Check that `DailyNotificationReceiver` is registered in AndroidManifest.xml
|
||||
2. Verify permissions are requested at runtime (Android 13+)
|
||||
3. Check that notification channel is created
|
||||
4. Enable "Exact alarms" in app settings (Android 12+)
|
||||
|
||||
### iOS: Background Tasks Not Running
|
||||
1. Ensure Background Modes capability is enabled in Xcode
|
||||
2. Check that BGTaskScheduler identifiers match Info.plist
|
||||
3. Test on real device (simulator has limitations)
|
||||
4. Check iOS Settings → Notifications → TimeSafari
|
||||
|
||||
### Permission Issues
|
||||
1. Request permissions before scheduling: `requestPermissions()`
|
||||
2. Check permission status: `checkPermissions()`
|
||||
3. Guide users to system settings if denied
|
||||
|
||||
## Plugin Documentation
|
||||
|
||||
For complete plugin documentation, see:
|
||||
- Plugin README: `node_modules/@timesafari/daily-notification-plugin/README.md`
|
||||
- Plugin version: 1.0.11
|
||||
- Repository: https://gitea.anomalistdesign.com/trent_larson/daily-notification-plugin
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Android: Notification appears at scheduled time
|
||||
- [ ] Android: Notification survives app close
|
||||
- [ ] Android: Notification survives device reboot
|
||||
- [ ] iOS: Notification appears at scheduled time
|
||||
- [ ] iOS: Background fetch works
|
||||
- [ ] iOS: Notification survives app close
|
||||
- [ ] Web: Existing web push still works
|
||||
- [ ] Platform detection works correctly
|
||||
- [ ] Permission requests work on all platforms
|
||||
- [ ] Status retrieval works correctly
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ **Phase 1 Complete**: Native infrastructure configured
|
||||
🔄 **Phase 2 In Progress**: Ready for UI integration
|
||||
⏳ **Phase 3 Pending**: Web Push service integration
|
||||
⏳ **Phase 4 Pending**: Testing and validation
|
||||
⏳ **Phase 5 Pending**: Xcode capabilities setup
|
||||
Reference in New Issue
Block a user