notification_sync_kit 0.2.0

Capture Android notifications, persist them to a local queue, and sync them to your server via HTTP with Bearer token auth and automatic retry. Enriches each notification with GPS speed, location, and [...]

Changelog

All notable changes to notification_sync_kit will be documented in this file.

The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

0.2.0 — 2026-05-25

Breaking changes

• NotificationRecord.raw removed. The untyped Map<String, dynamic> raw field has been deleted. Fields previously accessed via raw are now promoted to typed top-level fields (see Added below).
• Records are emitted only after removal. The stream no longer emits on onNotificationPosted; it emits on onNotificationRemoved so every record arrives fully resolved with its interaction type and delay.

Added

• InteractionType enum (ignored, dismissed, opened, replied) with toJson() / fromJson() that serialise to uppercase strings matching the backend contract. fromJson falls back to ignored for unknown or null values.
• New NotificationRecord fields:
  • canReply (bool) — whether the notification had an inline-reply action.
  • haveExtraPicture (bool) — whether the notification contained an image.
  • speedKmph (double?) — vehicle speed in km/h at notification arrival; null if GPS unavailable.
  • latitude (double?) — device latitude at notification arrival.
  • longitude (double?) — device longitude at notification arrival.
  • interactionType (InteractionType) — what the driver did: OPENED, DISMISSED, REPLIED, or IGNORED. Defaults to ignored.
  • interactionDelayMs (int?) — milliseconds between notification arrival and driver action; null if removal was never observed.
• NotificationRecord.copyWith() — immutable update helper; allows updating hasRemoved, speedKmph, latitude, longitude, interactionType, and interactionDelayMs while preserving all other fields.
• InteractionDetector service (lib/src/services/interaction_detector.dart):
  • Uses Android UsageStatsManager via a MethodChannel (notification_sync_kit/usage_stats) to detect whether the driver opened the app after dismissing a notification.
  • Detection precedence: IGNORED (delay > 5 min) → OPENED (app foregrounded within 3 s of removal, detected via UsageStats after a 1.5 s settle delay) → REPLIED (heuristic: canReply=true, removed within 15 s, app not opened) → DISMISSED.
  • Degrades gracefully to DISMISSED when Usage Access permission is absent.
  • hasPermission(), requestPermission(), detect() public API.
  • Channel name configurable via constructor (channelName parameter) for easier testing.
• NotificationListenerController updates:
  • Accepts an optional interactionDetector: named parameter; defaults to a fresh InteractionDetector() instance if not supplied.
  • GPS is sampled (via geolocator, 3 s timeout, high accuracy) on onNotificationPosted and attached to the record on removal via an internal _pending map keyed by packageName|eventId.
  • New dispose() method cancels the source subscription and closes the broadcast stream controller.
• NotificationConfig (lib/src/services/notification_config.dart) — persists the server endpoint URL and Bearer token across app restarts using SharedPreferences. Exposes init(), endpoint, token, isConfigured, setEndpoint(), and setToken(). Now exported from the package barrel.
• SettingsPage (lib/src/ui/settings_page.dart) — Flutter settings screen for configuring the server endpoint and Bearer token, with URL validation and a show/hide toggle for the token field. Now exported from the package barrel.
• Structured logging (lib/src/logging.dart):
  • setupNotificationSyncKitLogging({Level level, bool includeTimestamp}) helper for consumers to enable console output with a single call.
  • Hierarchical loggers on every service: notification_sync_kit.controller, .detector, .uploader, .sync, .store.
• BACKEND_PAYLOAD.md — reference document describing the exact JSON payload sent to the backend, with field descriptions, interaction type definitions, real-world examples, derivable backend metrics, and HTTP request format.
• NotificationDetailPage now shows a Driver Context section (speed, location, interaction type, response time, canReply, hasPicture) in place of the removed Raw Data expansion tile.

Dependencies

• Added geolocator: ^13.0.0 for GPS speed and coordinates.
• Added logging: ^1.2.0 for structured per-component logging.

Android setup (required for upgraders)

• Add PACKAGE_USAGE_STATS permission to AndroidManifest.xml.
• Implement the notification_sync_kit/usage_stats MethodChannel in MainActivity.kt (see README for the full snippet).

---

0.1.0 — 2026-05-12

Added

• NotificationRecord model with full JSON serialization (toJson, fromJson, encodeList, decodeList) and a fromServiceEvent factory.
• NotificationListenerController — wraps notification_listener_service and exposes incoming notifications as a typed Stream<NotificationRecord>.
• NotificationQueueStore — SharedPreferences-backed persistent queue with add, readAll, count, removeById, and removeByIds.
• NotificationUploader — HTTP POST with optional Bearer token auth, configurable endpoint, and graceful error handling.
• NotificationSyncManager — periodic (default 30 s) flush of queued records with automatic removal of successfully uploaded entries and retry of failures.
• NotificationDetailPage — optional Flutter widget to display a single NotificationRecord with normalized and raw JSON views.
• Barrel export at lib/notification_sync_kit.dart for a single import.
• Example app in example/ demonstrating instant-upload + queue-fallback flow.