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

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

npx cap sync
# or
npx cap sync android
npx cap sync ios

Build Android

npm run build:android
# or
npm run build:android:debug

Build iOS

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