crowd-funder-for-time-pwa/doc/daily-notification-plugin-integration.md

# 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