Merge pull request #213 from flutter-news-app-full-source-code/feat/handle-push-notification-reception

Feat/handle push notification reception

Author: fulleni

.gitignore

@@ -52,6 +52,8 @@ unlinked_spec.ds
 **/android/app/debug
 **/android/app/profile
 **/android/app/release
+**/android/app/google-services.json
+
 *.jks
 
 # iOS/XCode related

README.md

@@ -38,11 +38,21 @@ A beautiful, infinitely scrolling feed serves as the core of the user experience
 ### 🔎 Powerful Content Curation & Discovery
 Give users the tools to find exactly what they're looking for with a multi-faceted discovery system.
 - **Customizable Filter Bar:** A persistent, one-tap filter bar provides instant access to pre-defined and user-created content streams.
-- **Advanced Content Curation:** A dedicated management UI allows users to construct, save, and manage highly specific news feeds. Users can save frequently used filters for on-demand use and pin them for one-tap access on the main feed.
+- **Advanced Content Curation:** A dedicated saved filter hub allows users to construct, save, and manage highly specific news feeds. Users can save frequently used filters for on-demand use and pin them for one-tap access on the main feed.
 - **Proactive Notification Subscriptions:** When saving a filter, users can subscribe to receive push notifications—such as breaking news alerts or daily digests—for content that matches their specific criteria.
 - **Dedicated Discovery Hub:** Users can browse publishers by category in horizontally scrolling carousels, apply regional filters, and perform targeted searches.
 > **Your Advantage:** Deliver powerful content discovery tools that keep users engaged, increase session duration, and encourage return visits.
 
+---
+
+### 🔔 Proactive & Flexible Push Notifications
+A robust, backend-driven notification system keeps users informed and brings them back to the content they care about.
+- **Multi-Provider Architecture:** Built on an abstraction that supports any push notification service. It ships with production-ready providers for Firebase (FCM) and OneSignal.
+- **Remote Provider Switching:** The primary notification provider is selected via remote configuration, allowing you to switch services on the fly without shipping an app update.
+- **Intelligent Deep-Linking:** Tapping a notification opens the app and navigates directly to the relevant content, such as a specific news article, providing a seamless user experience.
+- **Foreground Notification Handling:** Displays a subtle in-app indicator when a notification arrives while the user is active, avoiding intrusive alerts.
+> **Your Advantage:** You get a highly flexible and scalable notification system that avoids vendor lock-in and is ready to re-engage users from day one.
+
 </details>
 
 <details>

android/app/google-services.json

@@ -11,6 +11,7 @@ import 'package:flutter_news_app_mobile_client_full_source_code/ads/services/inl
 import 'package:flutter_news_app_mobile_client_full_source_code/app/models/app_life_cycle_status.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/models/initialization_result.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/services/app_initializer.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/notifications/services/push_notification_service.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/shared/extensions/extensions.dart';
 import 'package:logging/logging.dart';
 
@@ -45,12 +46,14 @@ class AppBloc extends Bloc<AppEvent, AppState> {
     required InlineAdCacheService inlineAdCacheService,
     required Logger logger,
     required DataRepository<User> userRepository,
+    required PushNotificationService pushNotificationService,
   }) : _remoteConfigRepository = remoteConfigRepository,
        _appInitializer = appInitializer,
        _authRepository = authRepository,
        _userAppSettingsRepository = userAppSettingsRepository,
        _userContentPreferencesRepository = userContentPreferencesRepository,
        _userRepository = userRepository,
+       _pushNotificationService = pushNotificationService,
        _inlineAdCacheService = inlineAdCacheService,
        _logger = logger,
        super(
@@ -79,7 +82,19 @@ class AppBloc extends Bloc<AppEvent, AppState> {
     on<SavedHeadlineFilterUpdated>(_onSavedHeadlineFilterUpdated);
     on<SavedHeadlineFilterDeleted>(_onSavedHeadlineFilterDeleted);
     on<SavedHeadlineFiltersReordered>(_onSavedHeadlineFiltersReordered);
+    on<AppPushNotificationDeviceRegistered>(
+      _onAppPushNotificationDeviceRegistered,
+    );
+    on<AppInAppNotificationReceived>(_onAppInAppNotificationReceived);
     on<AppLogoutRequested>(_onLogoutRequested);
+    on<AppPushNotificationTokenRefreshed>(_onAppPushNotificationTokenRefreshed);
+
+    // Listen to token refresh events from the push notification service.
+    // When a token is refreshed, dispatch an event to trigger device
+    // re-registration with the backend.
+    _pushNotificationService.onTokenRefreshed.listen((_) {
+      add(const AppPushNotificationTokenRefreshed());
+    });
   }
 
   final Logger _logger;
@@ -90,6 +105,7 @@ class AppBloc extends Bloc<AppEvent, AppState> {
   final DataRepository<UserContentPreferences>
   _userContentPreferencesRepository;
   final DataRepository<User> _userRepository;
+  final PushNotificationService _pushNotificationService;
   final InlineAdCacheService _inlineAdCacheService;
 
   /// Handles the [AppStarted] event.
@@ -101,6 +117,12 @@ class AppBloc extends Bloc<AppEvent, AppState> {
     _logger.fine(
       '[AppBloc] AppStarted event received. State is already initialized.',
     );
+
+    // If a user is already logged in when the app starts, register their
+    // device for push notifications.
+    if (state.user != null) {
+      await _registerDeviceForPushNotifications(state.user!.id);
+    }
   }
 
   /// Handles all logic related to user authentication state changes.
@@ -210,6 +232,11 @@ class AppBloc extends Bloc<AppEvent, AppState> {
             clearError: true,
           ),
         );
+
+        // After any successful user transition (including guest), attempt to
+        // register their device for push notifications. This ensures that
+        // guests can also receive notifications.
+        await _registerDeviceForPushNotifications(user.id);
       // If the transition fails (e.g., due to a network error while
       // fetching user data), emit a critical error state.
       case InitializationFailure(:final status, :final error):
@@ -576,4 +603,71 @@ class AppBloc extends Bloc<AppEvent, AppState> {
       'with reordered filters.',
     );
   }
+
+  /// Handles the [AppPushNotificationDeviceRegistered] event.
+  ///
+  /// This handler is primarily for logging and does not change the state.
+  void _onAppPushNotificationDeviceRegistered(
+    AppPushNotificationDeviceRegistered event,
+    Emitter<AppState> emit,
+  ) {
+    _logger.info('[AppBloc] Push notification device registration noted.');
+  }
+
+  /// Handles the [AppInAppNotificationReceived] event.
+  ///
+  /// This handler updates the state to indicate that a new, unread in-app
+  /// notification has been received, which can be used to show a UI indicator.
+  void _onAppInAppNotificationReceived(
+    AppInAppNotificationReceived event,
+    Emitter<AppState> emit,
+  ) {
+    emit(state.copyWith(hasUnreadInAppNotifications: true));
+  }
+
+  /// Handles the [AppPushNotificationTokenRefreshed] event.
+  ///
+  /// This event is triggered when the underlying push notification provider
+  /// (e.g., FCM, OneSignal) refreshes its device token. The AppBloc then
+  /// attempts to re-register the device with the backend using the current
+  /// user's ID.
+  Future<void> _onAppPushNotificationTokenRefreshed(
+    AppPushNotificationTokenRefreshed event,
+    Emitter<AppState> emit,
+  ) async {
+    if (state.user == null) {
+      _logger.info('[AppBloc] Skipping token re-registration: User is null.');
+      return;
+    }
+    _logger.info(
+      '[AppBloc] Push notification token refreshed. Re-registering device.',
+    );
+    await _registerDeviceForPushNotifications(state.user!.id);
+  }
+
+  /// A private helper method to encapsulate the logic for registering a
+  /// device for push notifications.
+  ///
+  /// This method is called from multiple places (`_onAppStarted`,
+  /// `_onAppUserChanged`, `_onAppPushNotificationTokenRefreshed`) to avoid
+  /// code duplication. It includes robust error handling to prevent unhandled
+  /// exceptions from crashing the BLoC.
+  Future<void> _registerDeviceForPushNotifications(String userId) async {
+    _logger.info(
+      '[AppBloc] Attempting to register device for push notifications for user $userId.',
+    );
+    try {
+      // The PushNotificationService handles getting the token and calling the
+      // repository's create method. The `registerDevice` method implements a
+      // "delete-then-create" pattern for idempotency.
+      await _pushNotificationService.registerDevice(userId: userId);
+      add(const AppPushNotificationDeviceRegistered());
+    } catch (e, s) {
+      _logger.severe(
+        '[AppBloc] Failed to register push notification device for user $userId.',
+        e,
+        s,
+      );
+    }
+  }
 }

lib/app/bloc/app_bloc.dart

@@ -184,3 +184,36 @@ class SavedHeadlineFiltersReordered extends AppEvent {
   @override
   List<Object> get props => [reorderedFilters];
 }
+
+/// {@template app_push_notification_device_registered}
+/// Dispatched when a push notification device has been successfully registered
+/// with the backend.
+///
+/// This event is for logging and potential future state changes, but does not
+/// directly alter the UI state in the current implementation.
+/// {@endtemplate}
+class AppPushNotificationDeviceRegistered extends AppEvent {
+  /// {@macro app_push_notification_device_registered}
+  const AppPushNotificationDeviceRegistered();
+}
+
+/// {@template app_in_app_notification_received}
+/// Dispatched when a push notification is received while the app is in the
+/// foreground, used to show an unread indicator.
+/// {@endtemplate}
+class AppInAppNotificationReceived extends AppEvent {
+  /// {@macro app_in_app_notification_received}
+  const AppInAppNotificationReceived();
+}
+
+/// {@template app_push_notification_token_refreshed}
+/// Dispatched when the underlying push notification provider refreshes its
+/// device token.
+///
+/// This event triggers the AppBloc to re-register the device with the backend
+/// using the current user's ID.
+/// {@endtemplate}
+class AppPushNotificationTokenRefreshed extends AppEvent {
+  /// {@macro app_push_notification_token_refreshed}
+  const AppPushNotificationTokenRefreshed();
+}

lib/app/bloc/app_event.dart

@@ -19,6 +19,7 @@ class AppState extends Equatable {
     this.selectedBottomNavigationIndex = 0,
     this.currentAppVersion,
     this.latestAppVersion,
+    this.hasUnreadInAppNotifications = false,
   });
 
   /// The current status of the application, indicating its lifecycle stage.
@@ -55,6 +56,9 @@ class AppState extends Equatable {
   /// The latest required app version, passed from [InitializationFailure].
   final String? latestAppVersion;
 
+  /// A flag indicating if there are unread in-app notifications.
+  final bool hasUnreadInAppNotifications;
+
   /// The current theme mode (light, dark, or system), derived from [settings].
   /// Defaults to [ThemeMode.system] if [settings] are not yet loaded.
   ThemeMode get themeMode {
@@ -123,6 +127,7 @@ class AppState extends Equatable {
     selectedBottomNavigationIndex,
     currentAppVersion,
     latestAppVersion,
+    hasUnreadInAppNotifications,
   ];
 
   /// Creates a copy of this [AppState] with the given fields replaced with
@@ -139,6 +144,7 @@ class AppState extends Equatable {
     int? selectedBottomNavigationIndex,
     String? currentAppVersion,
     String? latestAppVersion,
+    bool? hasUnreadInAppNotifications,
   }) {
     return AppState(
       status: status ?? this.status,
@@ -153,6 +159,8 @@ class AppState extends Equatable {
           selectedBottomNavigationIndex ?? this.selectedBottomNavigationIndex,
       currentAppVersion: currentAppVersion ?? this.currentAppVersion,
       latestAppVersion: latestAppVersion ?? this.latestAppVersion,
+      hasUnreadInAppNotifications:
+          hasUnreadInAppNotifications ?? this.hasUnreadInAppNotifications,
     );
   }
 }