trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity
Files
d583b9103ce5de18b9b3af9168cc0a550302b348
daily-notification-plugin/doc/directives/0003-iOS-Android-Parity-Directive.md
Matthew Raymer d583b9103c chore: new directive for implementation
2025-11-13 09:17:14 +00:00

44 KiB
Raw Blame History

iOS Android Parity Directive — iOS Implementation Upgrade

Status: 🎯 PLANNING - Directive for iOS-2 branch
Date: 2025-11-13
Author: Matthew Raymer
Branch: ios-2
Objective: Upgrade iOS implementation to match Android functionality while preserving Android code and TypeScript interface

Executive Summary

This directive outlines the plan to upgrade the iOS implementation of the Daily Notification Plugin to achieve feature parity with the functioning Android implementation. The Android codebase and TypeScript interface definitions will remain completely untouched during this work.

Key Constraints

  • ✅ Android code must remain unchanged - No modifications to src/android/ directory
  • ✅ TypeScript interface must remain unchanged - No modifications to src/definitions.ts
  • ✅ iOS implementation must match Android functionality - All Android @PluginMethod methods must have iOS equivalents
  • ✅ Platform-specific adaptations allowed - iOS can use Swift/iOS APIs but must provide same functionality

Testing & Scope

  • ✅ Primary Testing Target: iOS Simulator
  • ✅ Initial Scope: One scheduled prefetch + one scheduled notification per day
    • Prefetch Timing: 5 minutes before notification time
    • Notification Timing: User-specified daily time
  • ✅ Test App: ios-test-app (equivalent to android-test-app) with same HTML/JS UI
  • ✅ Rolling Window: Deferred to Phase 2 (initial implementation supports single daily schedule)

Readiness Milestones

  • Phase 1: Test app ready for basic testing (one prefetch + one notification per day)
  • Phase 3: Library ready for TimeSafari integration
  • Phase 4: Full library ready for production TimeSafari integration

Current State Assessment

Android Implementation (Reference)

Location: src/android/DailyNotificationPlugin.java

Key Components:

  • ✅ DailyNotificationPlugin.java - Main plugin class (1936 lines)
  • ✅ DailyNotificationStorage.java - Storage abstraction
  • ✅ DailyNotificationScheduler.java - AlarmManager-based scheduling
  • ✅ DailyNotificationFetcher.java - Background content fetching
  • ✅ DailyNotificationDatabase.java - SQLite database management
  • ✅ DailyNotificationRollingWindow.java - Rolling window safety
  • ✅ DailyNotificationExactAlarmManager.java - Exact alarm management
  • ✅ DailyNotificationRebootRecoveryManager.java - Reboot recovery
  • ✅ DailyNotificationTTLEnforcer.java - TTL enforcement
  • ✅ DailyNotificationETagManager.java - ETag caching
  • ✅ DailyNotificationJWTManager.java - JWT authentication
  • ✅ EnhancedDailyNotificationFetcher.java - TimeSafari API integration
  • ✅ DailyNotificationFetchWorker.java - WorkManager background worker
  • ✅ DailyNotificationReceiver.java - Broadcast receiver for alarms

Implemented Methods (from Android):

  1. configure() - Plugin configuration with database/storage options
  2. scheduleDailyNotification() - Schedule daily notification
  3. getLastNotification() - Get last delivered notification
  4. cancelAllNotifications() - Cancel all scheduled notifications
  5. getNotificationStatus() - Get current notification status
  6. updateSettings() - Update notification settings
  7. getBatteryStatus() - Get battery status information
  8. requestBatteryOptimizationExemption() - Request battery optimization exemption
  9. setAdaptiveScheduling() - Enable/disable adaptive scheduling
  10. getPowerState() - Get current power state
  11. maintainRollingWindow() - Manual rolling window maintenance
  12. getRollingWindowStats() - Get rolling window statistics
  13. getExactAlarmStatus() - Get exact alarm status
  14. requestExactAlarmPermission() - Request exact alarm permission
  15. openExactAlarmSettings() - Open exact alarm settings
  16. getRebootRecoveryStatus() - Get reboot recovery status
  17. setActiveDidFromHost() - Set activeDid from host (Phase 1)
  18. refreshAuthenticationForNewIdentity() - Refresh authentication (Phase 1)
  19. clearCacheForNewIdentity() - Clear cache for new identity (Phase 1)
  20. updateBackgroundTaskIdentity() - Update background task identity (Phase 1)
  21. testJWTGeneration() - Test JWT generation (Phase 1)
  22. testEndorserAPI() - Test Endorser.ch API (Phase 1)
  23. coordinateBackgroundTasks() - Coordinate background tasks (Phase 3)
  24. handleAppLifecycleEvent() - Handle app lifecycle events (Phase 3)
  25. getCoordinationStatus() - Get coordination status (Phase 3)
  26. scheduleDailyReminder() - Schedule static daily reminder
  27. cancelDailyReminder() - Cancel daily reminder
  28. getScheduledReminders() - Get all scheduled reminders
  29. updateDailyReminder() - Update existing daily reminder

iOS Implementation (Current)

Location: ios/Plugin/DailyNotificationPlugin.swift

Current Components:

  • ✅ DailyNotificationPlugin.swift - Main plugin class (480 lines, partial)
  • ✅ DailyNotificationDatabase.swift - CoreData database (exists)
  • ✅ DailyNotificationRollingWindow.swift - Rolling window (exists)
  • ✅ DailyNotificationTTLEnforcer.swift - TTL enforcer (exists)
  • ✅ DailyNotificationETagManager.swift - ETag manager (exists)
  • ✅ DailyNotificationBackgroundTaskManager.swift - Background task manager (exists)
  • ✅ DailyNotificationConstants.swift - Constants (exists)
  • ✅ DailyNotificationErrorHandler.swift - Error handling (exists)
  • ✅ DailyNotificationLogger.swift - Logging (exists)
  • ✅ DailyNotificationPowerManager.swift - Power management (exists)
  • ✅ DailyNotificationPerformanceOptimizer.swift - Performance (exists)
  • ✅ DailyNotificationCallbacks.swift - Callbacks (exists)
  • ✅ DailyNotificationConfig.swift - Configuration (exists)
  • ✅ DailyNotificationModel.swift - Data models (exists)
  • ✅ DailyNotificationMaintenanceWorker.swift - Maintenance (exists)

Currently Implemented Methods:

  1. ✅ configure() - Basic configuration (needs enhancement)
  2. ✅ scheduleContentFetch() - Basic BGTaskScheduler (needs enhancement)
  3. ✅ scheduleUserNotification() - Basic UNUserNotificationCenter (needs enhancement)
  4. ✅ scheduleDualNotification() - Dual scheduling (needs enhancement)
  5. ✅ getDualScheduleStatus() - Status retrieval (needs enhancement)
  6. ✅ scheduleDailyReminder() - Static reminders (implemented)
  7. ✅ cancelDailyReminder() - Cancel reminders (implemented)
  8. ✅ getScheduledReminders() - Get reminders (implemented)
  9. ✅ updateDailyReminder() - Update reminders (implemented)

Missing Methods (Need Implementation):

  1. ❌ scheduleDailyNotification() - Main scheduling method
  2. ❌ getLastNotification() - Last notification retrieval
  3. ❌ cancelAllNotifications() - Cancel all notifications
  4. ❌ getNotificationStatus() - Status retrieval
  5. ❌ updateSettings() - Settings update
  6. ❌ getBatteryStatus() - Battery status
  7. ❌ requestBatteryOptimizationExemption() - Battery optimization
  8. ❌ setAdaptiveScheduling() - Adaptive scheduling
  9. ❌ getPowerState() - Power state
  10. ❌ maintainRollingWindow() - Rolling window maintenance
  11. ❌ getRollingWindowStats() - Rolling window stats
  12. ❌ getExactAlarmStatus() - Exact alarm status (iOS equivalent)
  13. ❌ requestExactAlarmPermission() - Alarm permission (iOS equivalent)
  14. ❌ openExactAlarmSettings() - Alarm settings (iOS equivalent)
  15. ❌ getRebootRecoveryStatus() - Reboot recovery status
  16. ❌ setActiveDidFromHost() - ActiveDid management (Phase 1)
  17. ❌ refreshAuthenticationForNewIdentity() - Auth refresh (Phase 1)
  18. ❌ clearCacheForNewIdentity() - Cache clearing (Phase 1)
  19. ❌ updateBackgroundTaskIdentity() - Background task identity (Phase 1)
  20. ❌ testJWTGeneration() - JWT testing (Phase 1)
  21. ❌ testEndorserAPI() - API testing (Phase 1)
  22. ❌ coordinateBackgroundTasks() - Background coordination (Phase 3)
  23. ❌ handleAppLifecycleEvent() - Lifecycle events (Phase 3)
  24. ❌ getCoordinationStatus() - Coordination status (Phase 3)

Implementation Strategy

Testing Environment: iOS Simulator (primary testing target)

Initial Scope: Simplified daily schedule

  • One scheduled prefetch per day (via BGTaskScheduler)
    • Timing: 5 minutes before notification time
  • One scheduled notification per day (via UNUserNotificationCenter)
    • Timing: User-specified daily time
  • Full rolling window and advanced features deferred to later phases

Phase 1: Core Infrastructure Parity

Objective: Implement core notification scheduling and management methods with simplified daily schedule

Tasks:

  1. Storage Layer Enhancement

    • Enhance DailyNotificationStorage (Swift equivalent) to match Android DailyNotificationStorage.java
    • Support both UserDefaults and SQLite (CoreData) storage modes
    • Implement content caching and retrieval

  2. Scheduler Implementation

    • Create DailyNotificationScheduler.swift equivalent to DailyNotificationScheduler.java
    • Use UNUserNotificationCenter for notification scheduling
    • Initial: Support single daily notification (one prefetch + one notification per day)
    • Rolling window logic deferred to Phase 2

  3. Background Fetching

    • Enhance DailyNotificationBackgroundTaskManager.swift to match Android DailyNotificationFetcher.java
    • Implement BGTaskScheduler registration and execution
    • Initial: Support single daily prefetch task (scheduled 5 minutes before notification)
    • Add content fetching with ETag support

  4. Core Methods Implementation

    • scheduleDailyNotification() - Main scheduling method (single daily schedule)
    • getLastNotification() - Last notification retrieval
    • cancelAllNotifications() - Cancel all
    • getNotificationStatus() - Status retrieval
    • updateSettings() - Settings update

Platform Adaptations:

  • Android AlarmManager → iOS UNUserNotificationCenter with UNCalendarNotificationTrigger
  • Android WorkManager → iOS BGTaskScheduler with BGAppRefreshTaskRequest
  • Android SharedPreferences → iOS UserDefaults (with SQLite option via CoreData)

Test App Readiness: Phase 1 test app should be ready for testing on iOS Simulator after core methods are implemented

Phase 2: Advanced Features Parity

Objective: Implement advanced features matching Android capabilities

Tasks:

  1. Rolling Window Management

    • Enhance DailyNotificationRollingWindow.swift to match Android implementation
    • Implement iOS-specific limits (64 pending notifications)
    • Add maintenance scheduling
    • Note: Expands beyond single daily schedule to support rolling window

  2. TTL Enforcement

    • Enhance DailyNotificationTTLEnforcer.swift to match Android implementation
    • Implement TTL checking at notification fire time
    • Add stale content handling

  3. Exact Alarm Equivalent

    • Implement iOS equivalent of Android exact alarm management
    • Use UNTimeIntervalNotificationTrigger for precise timing
    • Handle iOS notification delivery guarantees

  4. Reboot Recovery

    • Create DailyNotificationRebootRecoveryManager.swift equivalent
    • Use iOS app launch detection to reschedule notifications
    • Implement recovery status tracking

  5. Power Management

    • Enhance DailyNotificationPowerManager.swift to match Android capabilities
    • Implement battery status checking
    • Add background refresh status checking

Platform Adaptations:

  • Android exact alarms → iOS notification delivery with time-based triggers
  • Android battery optimization → iOS Background App Refresh settings
  • Android reboot recovery → iOS app launch detection and rescheduling

Test App Readiness: Phase 2 test app should be ready for testing rolling window and advanced features on iOS Simulator

Phase 3: TimeSafari Integration Parity

Objective: Implement TimeSafari-specific integration features

Tasks:

  1. JWT Management

    • Create DailyNotificationJWTManager.swift equivalent
    • Implement JWT token generation and caching
    • Add token refresh logic

  2. ETag Management

    • Enhance DailyNotificationETagManager.swift to match Android
    • Implement ETag caching and conditional requests
    • Add ETag invalidation logic

  3. Enhanced Fetcher

    • Create EnhancedDailyNotificationFetcher.swift equivalent
    • Implement TimeSafari API integration
    • Add activeDid support

  4. Phase 1 Methods

    • setActiveDidFromHost() - ActiveDid management
    • refreshAuthenticationForNewIdentity() - Auth refresh
    • clearCacheForNewIdentity() - Cache clearing
    • updateBackgroundTaskIdentity() - Background task identity
    • testJWTGeneration() - JWT testing
    • testEndorserAPI() - API testing

Platform Adaptations:

  • Android WorkManager background tasks → iOS BGTaskScheduler background tasks
  • Android SharedPreferences for config → iOS UserDefaults for config
  • Android JWT signing → iOS JWT signing (same algorithm, different implementation)

TimeSafari Integration Readiness: Library ready for TimeSafari integration after Phase 3 completion Test App Readiness: Phase 3 test app should be ready for testing TimeSafari integration features on iOS Simulator

Phase 4: Background Coordination Parity

Objective: Implement background task coordination features

Tasks:

  1. Background Coordination

    • Implement coordinateBackgroundTasks() method
    • Add TimeSafari PlatformServiceMixin integration
    • Coordinate BGTaskScheduler with app lifecycle

  2. Lifecycle Management

    • Implement handleAppLifecycleEvent() method
    • Handle app background/foreground events
    • Sync state with app lifecycle

  3. Coordination Status

    • Implement getCoordinationStatus() method
    • Track coordination state
    • Provide debugging information

Platform Adaptations:

  • Android app lifecycle callbacks → iOS app lifecycle notifications
  • Android WorkManager coordination → iOS BGTaskScheduler coordination

TimeSafari Integration Readiness: Full library ready for production TimeSafari integration after Phase 4 completion Test App Readiness: Phase 4 test app should be ready for testing full background coordination on iOS Simulator

Component Mapping: Android → iOS

Core Components

Android Component iOS Equivalent Status Notes
DailyNotificationPlugin.java DailyNotificationPlugin.swift ✅ Partial Needs method additions
DailyNotificationStorage.java DailyNotificationStorage.swift ❌ Missing Create new file
DailyNotificationScheduler.java DailyNotificationScheduler.swift ❌ Missing Create new file
DailyNotificationFetcher.java DailyNotificationBackgroundTaskManager.swift ✅ Exists Needs enhancement
DailyNotificationDatabase.java DailyNotificationDatabase.swift ✅ Exists CoreData-based
DailyNotificationRollingWindow.java DailyNotificationRollingWindow.swift ✅ Exists Needs enhancement
DailyNotificationExactAlarmManager.java iOS equivalent needed ❌ Missing Use UNUserNotificationCenter
DailyNotificationRebootRecoveryManager.java iOS equivalent needed ❌ Missing Use app launch detection
DailyNotificationTTLEnforcer.java DailyNotificationTTLEnforcer.swift ✅ Exists Needs enhancement
DailyNotificationETagManager.java DailyNotificationETagManager.swift ✅ Exists Needs enhancement
DailyNotificationJWTManager.java iOS equivalent needed ❌ Missing Create new file
EnhancedDailyNotificationFetcher.java iOS equivalent needed ❌ Missing Create new file
DailyNotificationFetchWorker.java BGTaskScheduler handler ❌ Missing Implement in plugin
DailyNotificationReceiver.java Notification delegate ❌ Missing Implement in plugin

Platform API Mapping

Android API iOS Equivalent Implementation Notes
AlarmManager.setExact() UNUserNotificationCenter.add() with UNCalendarNotificationTrigger Use calendar-based triggers for daily scheduling
WorkManager.enqueue() BGTaskScheduler.submit() Use BGAppRefreshTaskRequest for background fetching
SharedPreferences UserDefaults For simple key-value storage
SQLiteDatabase CoreData / SQLite.swift For complex data storage
NotificationManager UNUserNotificationCenter For notification delivery
PowerManager UIDevice.batteryState For battery status
BroadcastReceiver App lifecycle notifications For reboot recovery
PendingIntent UNNotificationRequest For scheduled notifications

Method Implementation Checklist

Core Methods (Phase 1)

  • configure(options: ConfigureOptions) - Enhanced configuration
  • scheduleDailyNotification(options: NotificationOptions) - Main scheduling
  • getLastNotification() - Last notification retrieval
  • cancelAllNotifications() - Cancel all notifications
  • getNotificationStatus() - Status retrieval
  • updateSettings(settings: NotificationSettings) - Settings update
  • getBatteryStatus() - Battery status
  • requestBatteryOptimizationExemption() - Battery optimization (iOS: Background App Refresh)
  • setAdaptiveScheduling(options: { enabled: boolean }) - Adaptive scheduling
  • getPowerState() - Power state

Rolling Window Methods (Phase 2)

  • maintainRollingWindow() - Manual maintenance
  • getRollingWindowStats() - Statistics retrieval

Exact Alarm Methods (Phase 2) - iOS Equivalents

  • getExactAlarmStatus() - Notification delivery status
  • requestExactAlarmPermission() - Notification permissions
  • openExactAlarmSettings() - Open notification settings

Reboot Recovery Methods (Phase 2)

  • getRebootRecoveryStatus() - Recovery status

TimeSafari Integration Methods (Phase 3)

  • setActiveDidFromHost(options: { activeDid: string }) - ActiveDid management
  • refreshAuthenticationForNewIdentity(options: { activeDid: string }) - Auth refresh
  • clearCacheForNewIdentity() - Cache clearing
  • updateBackgroundTaskIdentity(options: { activeDid: string }) - Background task identity
  • testJWTGeneration(options?: { activeDid?: string }) - JWT testing
  • testEndorserAPI(options?: { activeDid?: string, apiServer?: string }) - API testing

Background Coordination Methods (Phase 4)

  • coordinateBackgroundTasks() - Background coordination
  • handleAppLifecycleEvent(options: { lifecycleEvent: string }) - Lifecycle events
  • getCoordinationStatus() - Coordination status

Enhanced Dual Scheduling Methods (Already Partially Implemented)

  • scheduleContentFetch(config: ContentFetchConfig) - Needs enhancement
  • scheduleUserNotification(config: UserNotificationConfig) - Needs enhancement
  • scheduleDualNotification(config: DualScheduleConfiguration) - Needs enhancement
  • getDualScheduleStatus() - Needs enhancement

Reminder Methods (Already Implemented)

  • scheduleDailyReminder(options: ReminderOptions) - ✅ Complete
  • cancelDailyReminder(options: { reminderId: string }) - ✅ Complete
  • getScheduledReminders() - ✅ Complete
  • updateDailyReminder(options: ReminderOptions) - ✅ Complete

Platform-Specific Considerations

Testing Environment

  • Primary Testing Target: iOS Simulator
  • Simulator Testing: All features should be testable on iOS Simulator
  • Physical Device Testing: Optional for final validation

iOS Notification Limits

  • Maximum Pending Notifications: 64 (system limit)
  • Maximum Daily Notifications: ~20 (recommended)
  • Initial Scope: One prefetch + one notification per day
  • Rolling Window Strategy: Always arm today's notifications, arm tomorrow's if within limits (Phase 2+)

iOS Background Execution

  • BGTaskScheduler Limits:
    • Background refresh tasks: ~30 seconds execution time
    • Processing tasks: Variable, depends on system resources
  • Strategy: Efficient processing, immediate next-schedule after completion

iOS Storage Options

  • UserDefaults: For simple configuration and preferences
  • CoreData: For complex relational data (schedules, content cache)
  • File System: For large content (images, media)

iOS Permission Model

  • Notification Permissions: Required for all notification delivery
  • Background App Refresh: Required for background fetching
  • Strategy: Request permissions early, provide clear explanations

Testing Strategy

Unit Tests

  • Test all new methods match Android behavior
  • Test storage layer (UserDefaults and CoreData)
  • Test scheduler with iOS notification limits
  • Test background task execution
  • Test TTL enforcement
  • Test rolling window maintenance

Integration Tests

  • Test full notification pipeline (fetch → cache → schedule → display)
  • Test offline scenarios
  • Test background execution reliability
  • Test reboot recovery
  • Test activeDid integration

Manual Testing

  • Test on physical iOS devices
  • Test Background App Refresh settings
  • Test notification permissions
  • Test battery optimization scenarios
  • Test app lifecycle events

iOS Test App Requirements

UI Parity with Android

Objective: Create iOS test app with identical UI/UX to Android test app, using iOS plugin implementation

Reference App: test-apps/android-test-app/ (Standalone Android with HTML/JS UI)

Requirements:

  1. Same UI as Android Test App

    • Reuse exact HTML/JavaScript from android-test-app/app/src/main/assets/public/index.html
    • Same button layout and functionality
    • Same status display area
    • Same visual design and styling
    • Platform detection to use iOS plugin methods instead of Android

  2. Platform Detection

    • Detect iOS platform and use iOS plugin methods
    • Show iOS-specific status indicators
    • Display iOS-specific permission states
    • Adapt Android-specific methods to iOS equivalents (e.g., openExactAlarmSettings → openNotificationSettings)

  3. iOS Plugin Integration

    • Use iOS DailyNotificationPlugin instead of Android version
    • All method calls route to iOS native implementation
    • Error handling adapted for iOS-specific errors

File Structure:

test-apps/ios-test-app/
├── App/
│   ├── AppDelegate.swift                  # App delegate with plugin setup
│   ├── Info.plist                         # iOS permissions and config
│   ├── SceneDelegate.swift                # Scene management (if needed)
│   └── Main.storyboard                    # Main storyboard (if needed)
├── App.xcodeproj/                          # Xcode project
├── App.xcworkspace/                        # Xcode workspace (if using CocoaPods)
├── Podfile                                # CocoaPods dependencies
└── www/                                    # Web assets (HTML/JS/CSS)
    ├── index.html                          # Same UI as android-test-app
    ├── capacitor.config.json               # Capacitor config
    └── capacitor.plugins.json              # Plugin registration

iOS Permissions and Requirements

Required Permissions (Info.plist):

  1. Notification Permissions

    <key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
    <string>fetch</string>
    <string>processing</string>
</array>

  2. Background Task Identifiers

    <key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.timesafari.dailynotification.fetch</string>
    <string>com.timesafari.dailynotification.notify</string>
</array>

  3. Usage Descriptions

    <key>NSUserNotificationsUsageDescription</key>
<string>TimeSafari needs notification permissions to deliver daily updates</string>

Runtime Permission Handling:

  1. Notification Permissions

    • Request via UNUserNotificationCenter.requestAuthorization()
    • Check status via UNUserNotificationCenter.getNotificationSettings()
    • Display permission status in test app UI
    • Provide "Open Settings" button if denied

  2. Background App Refresh

    • Check status via UIApplication.shared.backgroundRefreshStatus
    • Display status in test app UI
    • Provide guidance for enabling in Settings

  3. Permission Status Display

    • Show notification permission state (authorized/denied/not determined)
    • Show background refresh state (available/restricted/denied)
    • Show battery optimization status (iOS equivalent)
    • Provide actionable buttons to request/enable permissions

iOS-Specific Requirements:

  1. Background Task Registration

    • Register BGTaskScheduler tasks in AppDelegate.application(_:didFinishLaunchingWithOptions:)
    • Register handlers before app finishes launching
    • Handle task expiration gracefully

  2. Notification Categories

    • Define notification categories for actions
    • Register categories with UNUserNotificationCenter
    • Handle notification actions in delegate

  3. App Lifecycle Integration

    • Handle app background/foreground events
    • Reschedule notifications on app launch
    • Sync state on app resume

Build Options

Objective: Support both Xcode GUI and command-line builds with straightforward setup

Xcode Build (GUI)

Setup:

  1. Open test-apps/ios-test-app/App.xcworkspace (if using CocoaPods) or App.xcodeproj in Xcode
  2. Select target device (simulator or physical device)
  3. Build and run via Xcode interface

Xcode Configuration:

  • Scheme: ios-test-app (or similar)
  • Configuration: Debug (development) / Release (production)
  • Signing: Automatic signing with development team
  • Capabilities:
    • Push Notifications
    • Background Modes (Remote notifications, Background fetch, Background processing)

Xcode Build Steps:

  1. Clean build folder (Cmd+Shift+K)
  2. Build project (Cmd+B)
  3. Run on device/simulator (Cmd+R)
  4. Attach debugger for debugging

Console Build (Command Line)

Objective: Enable straightforward command-line builds matching Android test app pattern

Build Script Pattern:

  • Follow pattern from scripts/build-native.sh
  • Create scripts/build-ios-test-app.sh for iOS test app
  • Support both simulator and device builds
  • Include dependency installation (CocoaPods)
  • Include code signing configuration

Build Commands (via Script):

  1. Build iOS Test App (Debug - Simulator)

    ./scripts/build-ios-test-app.sh --simulator

  2. Build iOS Test App (Debug - Device)

    ./scripts/build-ios-test-app.sh --device

  3. Build iOS Test App (Release)

    ./scripts/build-ios-test-app.sh --release

Direct xcodebuild Commands (if needed):

  1. Install Dependencies

    cd test-apps/ios-test-app
pod install  # If using CocoaPods

  2. Build iOS App (Debug - Simulator)

    xcodebuild -workspace App.xcworkspace \
  -scheme ios-test-app \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

  3. Build iOS App (Debug - Device)

    xcodebuild -workspace App.xcworkspace \
  -scheme ios-test-app \
  -configuration Debug \
  -sdk iphoneos \
  -destination 'generic/platform=iOS' \
  build

  4. Build iOS App (Release)

    xcodebuild -workspace App.xcworkspace \
  -scheme ios-test-app \
  -configuration Release \
  -sdk iphoneos \
  -archivePath build/ios-test-app.xcarchive \
  archive

Build Script Requirements:

  • Check for required tools (xcodebuild, pod if using CocoaPods)
  • Install dependencies automatically
  • Support both simulator and device builds
  • Provide clear error messages
  • Follow same pattern as scripts/build-native.sh (colors, logging, error handling)

Debugging Strategy

Objective: Make debugging easily accessible and comprehensive

Console Logging

Structured Logging:

  1. Log Levels

    • DEBUG: Detailed diagnostic information
    • INFO: General informational messages
    • WARN: Warning messages for potential issues
    • ERROR: Error messages for failures

  2. Log Format

    [DNP-PLUGIN] [LEVEL] [TIMESTAMP] [METHOD] Message

    Example:

    [DNP-PLUGIN] [INFO] [2025-11-13 10:30:45 UTC] [scheduleDailyNotification] Scheduling notification for 09:00

  3. Log Categories

    • DNP-PLUGIN: Main plugin operations
    • DNP-SCHEDULER: Scheduling operations
    • DNP-FETCHER: Background fetching
    • DNP-STORAGE: Storage operations
    • DNP-TTL: TTL enforcement
    • DNP-ROLLING-WINDOW: Rolling window maintenance

Logging Implementation:

  • Use os_log for system-level logging (visible in Console.app)
  • Use print() for Xcode console output
  • Include file/line information in debug builds
  • Support log level filtering

Xcode Debugging

Breakpoints:

  1. Strategic Breakpoints

    • Plugin method entry points
    • Background task handlers
    • Notification scheduling logic
    • Error handling paths

  2. Conditional Breakpoints

    • Break on specific notification IDs
    • Break on error conditions
    • Break on specific activeDid values

  3. Logging Breakpoints

    • Log method entry/exit without stopping
    • Log variable values
    • Log call stack

Debugging Tools:

  1. LLDB Commands

    • Inspect Swift objects
    • Print variable values
    • Execute Swift expressions
    • View call stack

  2. View Hierarchy Debugger

    • Inspect UI components
    • Debug layout issues
    • Verify UI state

  3. Network Debugging

    • Monitor API calls
    • Inspect request/response
    • Debug authentication issues

Test App Debugging UI

Debug Panel in Test App:

  1. Log Viewer

    • Real-time log display
    • Filter by log level
    • Filter by category
    • Search functionality
    • Export logs to file

  2. Status Dashboard

    • Plugin initialization status
    • Permission status
    • Background task status
    • Notification schedule status
    • Storage status

  3. Diagnostic Tools

    • Test individual plugin methods
    • View stored data (UserDefaults, CoreData)
    • Trigger manual background tasks
    • Force notification delivery
    • Clear caches

  4. Error Display

    • Show recent errors
    • Error details and stack traces
    • Error reporting functionality

Debug View Implementation:

<!-- DebugView.vue -->
<template>
  <div class="debug-view">
    <h2>🔍 Debug Tools</h2>
    
    <!-- Log Viewer -->
    <LogViewer :logs="logs" />
    
    <!-- Status Dashboard -->
    <StatusDashboard :status="pluginStatus" />
    
    <!-- Diagnostic Tools -->
    <DiagnosticTools @test-method="testMethod" />
    
    <!-- Error Display -->
    <ErrorDisplay :errors="errors" />
  </div>
</template>

Console.app Integration

System Logs:

  • Use os_log for system-level logging
  • View logs in Console.app on macOS
  • Filter by subsystem: com.timesafari.dailynotification
  • Export logs for analysis

Log Export:

  • Export logs from test app UI
  • Export via Xcode Organizer
  • Export via Console.app
  • Include timestamps and log levels

Background Task Debugging

BGTaskScheduler Debugging:

  1. Task Registration Verification

    • Log task registration in AppDelegate
    • Verify task identifiers match Info.plist
    • Check task handler registration

  2. Task Execution Monitoring

    • Log task start/completion
    • Log task expiration
    • Monitor task execution time
    • Track task success/failure

  3. Task Scheduling Debugging

    • Log scheduled task times
    • Verify earliestBeginDate
    • Check task submission success
    • Monitor task cancellation

Debug Commands:

// In test app or debug build
func debugBackgroundTasks() {
    // List registered tasks
    // Show scheduled tasks
    // Trigger test tasks
    // View task history
}

Notification Debugging

Notification Delivery Debugging:

  1. Scheduled Notifications

    • List all pending notifications
    • Show notification content
    • Display trigger times
    • Verify notification limits

  2. Notification Delivery

    • Log notification delivery
    • Track delivery success/failure
    • Monitor notification actions
    • Debug notification display

  3. Permission Debugging

    • Check permission status
    • Log permission requests
    • Track permission changes
    • Debug permission denials

Debug Methods:

// Debug notification state
func debugNotifications() {
    // Get pending notifications
    // Get delivered notifications
    // Check notification settings
    // Verify notification categories
}

Test App Implementation Checklist

  • Create ios-test-app directory structure (equivalent to android-test-app)
  • Copy HTML/JS UI from android-test-app/app/src/main/assets/public/index.html
  • Adapt JavaScript to use iOS plugin methods
  • Configure Info.plist with required permissions
  • Implement AppDelegate with plugin setup
  • Set up Xcode project/workspace
  • Configure CocoaPods (if needed) or direct dependencies
  • Create build script scripts/build-ios-test-app.sh
  • Test Xcode GUI builds
  • Test command-line builds via script
  • Implement comprehensive logging
  • Add Console.app integration
  • Create debugging documentation

File Organization

New Files to Create

ios/Plugin/
├── DailyNotificationStorage.swift          # Storage abstraction (new)
├── DailyNotificationScheduler.swift       # Scheduler implementation (new)
├── DailyNotificationJWTManager.swift      # JWT management (new)
├── EnhancedDailyNotificationFetcher.swift # Enhanced fetcher (new)
└── DailyNotificationRebootRecoveryManager.swift # Reboot recovery (new)

Files to Enhance

ios/Plugin/
├── DailyNotificationPlugin.swift          # Add missing methods
├── DailyNotificationBackgroundTaskManager.swift # Enhance background tasks
├── DailyNotificationRollingWindow.swift   # Enhance rolling window
├── DailyNotificationTTLEnforcer.swift     # Enhance TTL enforcement
└── DailyNotificationETagManager.swift     # Enhance ETag management

Test App Files to Create

test-apps/ios-test-app/                     # New iOS test app (equivalent to android-test-app)
├── App/
│   ├── AppDelegate.swift                  # App delegate with plugin setup
│   ├── Info.plist                         # iOS permissions and config
│   ├── SceneDelegate.swift                # Scene management (if needed)
│   └── Main.storyboard                    # Main storyboard (if needed)
├── App.xcodeproj/                          # Xcode project
├── App.xcworkspace/                        # Xcode workspace (if using CocoaPods)
├── Podfile                                # CocoaPods dependencies
└── www/                                    # Web assets (same as android-test-app)
    ├── index.html                          # Same UI as android-test-app
    ├── capacitor.config.json               # Capacitor config
    └── capacitor.plugins.json              # Plugin registration

Build Scripts to Create

scripts/
└── build-ios-test-app.sh                   # iOS test app build script (new)
    # Pattern: Similar to scripts/build-native.sh
    # Features:
    # - Check environment (xcodebuild, pod)
    # - Install dependencies (pod install)
    # - Build for simulator or device
    # - Clear error messages and logging

Success Criteria

Functional Parity

  • All Android @PluginMethod methods have iOS equivalents
  • All methods return same data structures as Android
  • All methods handle errors consistently with Android
  • All methods log consistently with Android

Platform Adaptations

  • iOS uses appropriate iOS APIs (UNUserNotificationCenter, BGTaskScheduler)
  • iOS respects iOS limits (64 notification limit, background execution limits)
  • iOS provides iOS-specific features where appropriate (Background App Refresh)

Code Quality

  • All code follows Swift best practices
  • All code is documented with file-level and method-level comments
  • All code includes error handling and logging
  • All code is type-safe

Testing

  • Unit tests cover all new methods
  • Integration tests verify full pipeline
  • Manual testing confirms real-world behavior

Test App

  • ios-test-app created with same UI as android-test-app
  • Test app uses iOS plugin implementation
  • All permissions properly configured in Info.plist
  • Build script build-ios-test-app.sh created and working
  • Build works via both Xcode GUI and command line
  • Comprehensive logging accessible via Console.app
  • Background task debugging tools available

Risks & Mitigations

Risk 1: iOS Background Execution Limitations

Risk: iOS background execution is more limited than Android
Mitigation:

  • Use efficient processing algorithms
  • Schedule next task immediately after completion
  • Provide clear user guidance on Background App Refresh

Risk 2: iOS Notification Limits

Risk: iOS 64 notification limit may conflict with rolling window strategy
Mitigation:

  • Implement smart rolling window that respects limits
  • Prioritize today's notifications over tomorrow's
  • Provide clear error messages when limits are reached

Risk 3: TypeScript Interface Compatibility

Risk: iOS implementation may not match TypeScript interface exactly
Mitigation:

  • Test all methods against TypeScript interface
  • Ensure return types match exactly
  • Ensure error handling matches Android behavior

Risk 4: Platform-Specific Behavior Differences

Risk: iOS and Android may behave differently for same operations
Mitigation:

  • Document all platform differences
  • Provide platform-specific error messages where appropriate
  • Test cross-platform compatibility

Timeline Estimate

Phase 1: Core Infrastructure

  • Storage layer implementation
  • Scheduler implementation (single daily schedule: one prefetch + one notification)
    • Prefetch scheduled 5 minutes before notification time
  • Background fetching enhancement (single daily prefetch, 5 minutes before notification)
  • Core methods implementation
  • iOS test app creation (ios-test-app)
  • Build script creation (build-ios-test-app.sh)
  • Testing on iOS Simulator

Test App Readiness: ✅ Ready for testing after Phase 1 completion

  • Basic scheduling (one prefetch 5 minutes before + one notification per day)
  • Core plugin methods functional
  • Testable on iOS Simulator

Phase 2: Advanced Features

  • Rolling window enhancement (expands beyond single daily schedule)
  • TTL enforcement enhancement
  • Exact alarm equivalent implementation
  • Reboot recovery implementation
  • Power management enhancement
  • Testing on iOS Simulator

Test App Readiness: ✅ Ready for testing after Phase 2 completion

  • Rolling window and advanced features functional
  • Testable on iOS Simulator

Phase 3: TimeSafari Integration

  • JWT management implementation
  • ETag management enhancement
  • Enhanced fetcher implementation
  • Phase 1 methods implementation
  • Testing on iOS Simulator

TimeSafari Integration Readiness: ✅ Library ready for TimeSafari integration after Phase 3 completion Test App Readiness: ✅ Ready for testing after Phase 3 completion

  • TimeSafari integration features functional
  • Testable on iOS Simulator

Phase 4: Background Coordination

  • Background coordination implementation
  • Lifecycle management implementation
  • Coordination status implementation
  • Testing on iOS Simulator

TimeSafari Integration Readiness: ✅ Full library ready for production TimeSafari integration after Phase 4 completion Test App Readiness: ✅ Ready for testing after Phase 4 completion

  • Full background coordination functional
  • Testable on iOS Simulator

Dependencies

External Dependencies

  • Capacitor: iOS plugin framework
  • UserNotifications: iOS notification framework
  • BackgroundTasks: iOS background execution framework
  • CoreData: iOS data persistence framework

Internal Dependencies

  • TypeScript Interface: Must remain unchanged (src/definitions.ts)
  • Android Implementation: Reference implementation (read-only)
  • Existing iOS Components: Build upon existing Swift files

References

Android Implementation Files

  • src/android/DailyNotificationPlugin.java - Main plugin class
  • src/android/DailyNotificationStorage.java - Storage layer
  • src/android/DailyNotificationScheduler.java - Scheduler
  • src/android/DailyNotificationFetcher.java - Background fetching
  • src/android/DailyNotificationDatabase.java - Database management
  • src/android/DailyNotificationRollingWindow.java - Rolling window
  • src/android/DailyNotificationExactAlarmManager.java - Exact alarms
  • src/android/DailyNotificationRebootRecoveryManager.java - Reboot recovery
  • src/android/DailyNotificationTTLEnforcer.java - TTL enforcement
  • src/android/DailyNotificationETagManager.java - ETag management
  • src/android/DailyNotificationJWTManager.java - JWT management
  • src/android/EnhancedDailyNotificationFetcher.java - Enhanced fetcher

iOS Implementation Files

  • ios/Plugin/DailyNotificationPlugin.swift - Main plugin class
  • ios/Plugin/DailyNotificationDatabase.swift - Database (CoreData)
  • ios/Plugin/DailyNotificationRollingWindow.swift - Rolling window
  • ios/Plugin/DailyNotificationTTLEnforcer.swift - TTL enforcement
  • ios/Plugin/DailyNotificationETagManager.swift - ETag management
  • ios/Plugin/DailyNotificationBackgroundTaskManager.swift - Background tasks

TypeScript Interface

  • src/definitions.ts - Complete TypeScript interface definition

Documentation

  • doc/implementation-roadmap.md - Implementation roadmap
  • doc/INTEGRATION_CHECKLIST.md - Integration checklist
  • README.md - Project documentation

Competence Hooks

Why This Works

  • Platform Parity: Matching Android functionality ensures consistent user experience across platforms
  • Incremental Approach: Phased implementation reduces risk and allows for iterative testing
  • Platform Adaptations: Using iOS-native APIs ensures optimal performance and reliability

Common Pitfalls

  • Background Execution Limits: iOS background execution is more limited than Android - must design for efficiency
  • Notification Limits: iOS 64 notification limit requires careful rolling window management
  • Permission Model: iOS requires explicit permission requests - must handle gracefully

Next Skill Unlock

  • iOS Background Execution: Understanding BGTaskScheduler and background execution patterns
  • iOS Notification System: Deep dive into UNUserNotificationCenter and notification delivery guarantees

Teach-Back

Question: "How does iOS background execution differ from Android, and how does this affect the notification scheduling strategy?"

Expected Answer: iOS background execution is more limited (30 seconds for refresh tasks) and less reliable than Android WorkManager. This requires efficient processing, immediate next-schedule after completion, and fallback strategies for when background execution fails.

Collaboration Hooks

Discussion Points

  1. Platform Differences: How should we handle platform-specific behavior differences in error messages and user guidance?
  2. Testing Strategy: What level of cross-platform testing is needed to ensure parity?
  3. Performance: How do we ensure iOS implementation performs as well as Android?

Review Points

  • Code Review: All new iOS code should be reviewed against Android implementation for functional parity
  • Architecture Review: iOS component architecture should be reviewed for maintainability
  • Testing Review: Test coverage should be reviewed for completeness

Stakeholders

  • iOS Developer: Primary implementer
  • Android Developer: Reference implementation owner (consultation)
  • TypeScript Developer: Interface maintainer (consultation)
  • QA: Testing and validation

Decision Log

2025-11-13: Directive Created

Decision: Create comprehensive directive for iOS Android parity implementation
Rationale: Need clear plan for upgrading iOS while preserving Android and TypeScript interface
Status: ✅ Approved for implementation

Status: 🎯 READY FOR IMPLEMENTATION
Next Steps: Begin Phase 1 implementation after directive approval

Reference in New Issue View Git Blame Copy Permalink