Merge pull request #81 from flutter-news-app-full-source-code/Decoupling-the-Ad-Subsystem

Decoupling the ad subsystem

Author: fulleni

README.md

@@ -29,6 +29,12 @@ This app comes packed with all the features you need to launch a professional ne
 *   Includes a dedicated search page to help users find specific content quickly.
 > **Your Advantage:** Give your users powerful content discovery tools that keep them engaged and coming back for more. 🎯
 
+#### 💰 **Extensible Monetization with In-Feed Ads**
+*   Built with a clean, provider-agnostic ad architecture that makes monetization simple and flexible.
+*   Features a decoupled design, allowing easy integration and swapping of various ad networks (e.g., Google AdMob, Meta Audience Network) without rewriting core logic.
+*   Comes with a ready-to-go Google AdMob integration for native ads in the feed.
+> **Your Advantage:** Start generating revenue from day one with a highly extensible and robust ad system that’s built to scale with your business. 💸
+
 #### 🔐 **Robust User Authentication**
 Secure and flexible authentication flows are built-in:
 *   📧 **Email + Code (Passwordless) Sign-In:** Modern and secure.
@@ -73,12 +79,6 @@ Easily switch between development (in-memory data or local API) and production e
 Fully internationalized with working English and Arabic localizations (`.arb` files). Adding more languages is straightforward.
 > **Your Advantage:** Easily adapt your application for a global audience and tap into new markets. 🌐
 
-#### 💰 **Extensible Monetization with In-Feed Ads**
-*   Built with a clean, provider-based ad architecture that makes monetization simple and flexible.
-*   Comes with a ready-to-go Google AdMob integration for native ads in the feed.
-*   The decoupled design means you can easily swap in or add other ad networks (like Meta Audience Network) in the future without rewriting your core logic.
-> **Your Advantage:** Start generating revenue from day one with a robust ad system that’s built to scale with your business. 💸
-
 ---
 
 ## 🔑 License: Source-Available with a Free Trial

lib/ads/ad_provider.dart

@@ -1,4 +1,5 @@
-import 'package:google_mobile_ads/google_mobile_ads.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/native_ad.dart'
+    as app_native_ad;
 
 /// {@template ad_provider}
 /// An abstract class defining the interface for any ad network provider.
@@ -19,9 +20,9 @@ abstract class AdProvider {
 
   /// Loads a native ad.
   ///
-  /// Returns a [NativeAd] object if an ad is successfully loaded,
+  /// Returns a [app_native_ad.NativeAd] object if an ad is successfully loaded,
   /// otherwise returns `null`.
-  Future<NativeAd?> loadNativeAd();
+  Future<app_native_ad.NativeAd?> loadNativeAd();
 
   // Future methods for other ad types (e.g., interstitial, banner)
   // can be added here as needed in the future.

lib/ads/ad_service.dart

@@ -17,8 +17,8 @@ class AdService {
   /// Requires an [AdProvider] to be injected, which will be used to
   /// load ads from a specific ad network.
   AdService({required AdProvider adProvider, Logger? logger})
-      : _adProvider = adProvider,
-        _logger = logger ?? Logger('AdService');
+    : _adProvider = adProvider,
+      _logger = logger ?? Logger('AdService');
 
   final AdProvider _adProvider;
   final Logger _logger;

lib/ads/admob_ad_provider.dart

@@ -2,20 +2,27 @@ import 'dart:async';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/ads/ad_provider.dart';
-import 'package:google_mobile_ads/google_mobile_ads.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/native_ad.dart'
+    as app_native_ad;
+import 'package:google_mobile_ads/google_mobile_ads.dart' as admob;
 import 'package:logging/logging.dart';
+import 'package:uuid/uuid.dart';
 
 /// {@template admob_ad_provider}
 /// A concrete implementation of [AdProvider] for Google AdMob.
 ///
 /// This class handles the initialization of the Google Mobile Ads SDK
-/// and the loading of native ads specifically for AdMob.
+/// and the loading of native ads specifically for AdMob. It adapts the
+/// AdMob-specific [admob.NativeAd] object into our generic [app_native_ad.NativeAd]
+/// model.
 /// {@endtemplate}
 class AdMobAdProvider implements AdProvider {
   /// {@macro admob_ad_provider}
-  AdMobAdProvider({Logger? logger}) : _logger = logger ?? Logger('AdMobAdProvider');
+  AdMobAdProvider({Logger? logger})
+    : _logger = logger ?? Logger('AdMobAdProvider');
 
   final Logger _logger;
+  final Uuid _uuid = const Uuid();
 
   /// The AdMob Native Ad Unit ID for Android.
   ///
@@ -54,7 +61,7 @@ class AdMobAdProvider implements AdProvider {
   Future<void> initialize() async {
     _logger.info('Initializing Google Mobile Ads SDK...');
     try {
-      await MobileAds.instance.initialize();
+      await admob.MobileAds.instance.initialize();
       _logger.info('Google Mobile Ads SDK initialized successfully.');
     } catch (e) {
       _logger.severe('Failed to initialize Google Mobile Ads SDK: $e');
@@ -64,24 +71,24 @@ class AdMobAdProvider implements AdProvider {
   }
 
   @override
-  Future<NativeAd?> loadNativeAd() async {
+  Future<app_native_ad.NativeAd?> loadNativeAd() async {
     if (_nativeAdUnitId.isEmpty) {
       _logger.warning('No native ad unit ID configured for this platform.');
       return null;
     }
 
     _logger.info('Attempting to load native ad from unit ID: $_nativeAdUnitId');
 
-    final completer = Completer<NativeAd?>();
+    final completer = Completer<admob.NativeAd?>();
 
-    final ad = NativeAd(
+    final ad = admob.NativeAd(
       adUnitId: _nativeAdUnitId,
       factoryId: 'listTile', // This ID must match a factory in your native code
-      request: const AdRequest(),
-      listener: NativeAdListener(
+      request: const admob.AdRequest(),
+      listener: admob.NativeAdListener(
         onAdLoaded: (ad) {
           _logger.info('Native Ad loaded successfully.');
-          completer.complete(ad as NativeAd);
+          completer.complete(ad as admob.NativeAd);
         },
         onAdFailedToLoad: (ad, error) {
           _logger.severe('Native Ad failed to load: $error');
@@ -114,6 +121,25 @@ class AdMobAdProvider implements AdProvider {
       completer.complete(null);
     }
 
-    return completer.future;
+    // Add a timeout to the future to prevent hanging if callbacks are not called.
+    final googleNativeAd = await completer.future.timeout(
+      const Duration(seconds: 15),
+      onTimeout: () {
+        _logger.warning('Native ad loading timed out.');
+        ad.dispose(); // Dispose the ad if it timed out
+        return null;
+      },
+    );
+
+    if (googleNativeAd == null) {
+      return null;
+    }
+
+    // Map the Google Mobile Ads NativeAd to our generic NativeAd model.
+    // Only the ID and the raw adObject are stored, as per the simplified model.
+    return app_native_ad.NativeAd(
+      id: _uuid.v4(), // Generate a unique ID for our internal model
+      adObject: googleNativeAd, // Store the original AdMob object
+    );
   }
 }

lib/ads/models/ad_feed_item.dart

@@ -1,31 +1,30 @@
 import 'package:core/core.dart';
 import 'package:equatable/equatable.dart';
-import 'package:google_mobile_ads/google_mobile_ads.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/native_ad.dart'
+    as app_native_ad;
 
 /// {@template ad_feed_item}
 /// A [FeedItem] that wraps a loaded native ad object from an ad network SDK.
 ///
-/// This class allows actual, displayable ad objects (like [NativeAd] from
-/// Google Mobile Ads) to be seamlessly integrated into the application's
+/// This class allows actual, displayable ad objects (like [app_native_ad.NativeAd]
+/// from our generic ad model) to be seamlessly integrated into the application's
 /// generic feed structure alongside other content types (e.g., [Headline]).
 /// {@endtemplate}
 class AdFeedItem extends FeedItem with EquatableMixin {
   /// {@macro ad_feed_item}
-  const AdFeedItem({
-    required this.id,
-    required this.nativeAd,
-  }) : super(type: 'ad_feed_item');
+  const AdFeedItem({required this.id, required this.nativeAd})
+    : super(type: 'ad_feed_item');
 
   /// A unique identifier for this specific ad instance in the feed.
   ///
   /// This is distinct from the ad unit ID and is used for tracking
   /// the ad within the feed.
   final String id;
 
-  /// The loaded native ad object from the ad network SDK.
+  /// The loaded native ad object, represented by our generic [app_native_ad.NativeAd] model.
   ///
   /// This object contains the actual ad content and is ready for display.
-  final NativeAd nativeAd;
+  final app_native_ad.NativeAd nativeAd;
 
   @override
   List<Object?> get props => [id, nativeAd, type];

lib/ads/models/models.dart

@@ -0,0 +1,2 @@
+export 'ad_feed_item.dart';
+export 'native_ad.dart';

lib/ads/models/native_ad.dart

@@ -0,0 +1,28 @@
+import 'package:equatable/equatable.dart';
+import 'package:flutter/foundation.dart';
+
+/// {@template native_ad}
+/// A generic, provider-agnostic model representing a native advertisement.
+///
+/// This model decouples the application's core logic from specific ad network
+/// SDKs (e.g., Google Mobile Ads). It holds a reference to the original,
+/// SDK-specific ad object for rendering purposes.
+/// {@endtemplate}
+@immutable
+class NativeAd extends Equatable {
+  /// {@macro native_ad}
+  const NativeAd({required this.id, required this.adObject});
+
+  /// A unique identifier for this specific native ad instance.
+  final String id;
+
+  /// The original, SDK-specific ad object.
+  ///
+  /// This object is passed directly to the ad network's UI widget for rendering.
+  /// It should be cast back to its specific type (e.g., `google_mobile_ads.NativeAd`)
+  /// only within the dedicated ad rendering widget for that provider.
+  final Object adObject;
+
+  @override
+  List<Object?> get props => [id, adObject];
+}

lib/ads/widgets/admob_native_ad_widget.dart

@@ -0,0 +1,83 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/native_ad.dart'
+    as app_native_ad;
+import 'package:google_mobile_ads/google_mobile_ads.dart' as admob;
+
+/// {@template admob_native_ad_widget}
+/// A widget responsible for rendering a Google AdMob native ad.
+///
+/// This widget takes our generic [app_native_ad.NativeAd] model, extracts
+/// the underlying [admob.NativeAd] object, and uses the AdMob SDK's
+/// [admob.AdWidget] to display it. It also handles the lifecycle
+/// management of the native ad object.
+/// {@endtemplate}
+class AdMobNativeAdWidget extends StatefulWidget {
+  /// {@macro admob_native_ad_widget}
+  const AdMobNativeAdWidget({required this.nativeAd, super.key});
+
+  /// The generic native ad data containing the AdMob-specific ad object.
+  final app_native_ad.NativeAd nativeAd;
+
+  @override
+  State<AdMobNativeAdWidget> createState() => _AdMobNativeAdWidgetState();
+}
+
+class _AdMobNativeAdWidgetState extends State<AdMobNativeAdWidget> {
+  admob.NativeAd? _admobNativeAd;
+  bool _isAdLoaded = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _initializeAd();
+  }
+
+  @override
+  void didUpdateWidget(covariant AdMobNativeAdWidget oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    // If the underlying ad object changes, dispose the old one and initialize the new one.
+    if (widget.nativeAd.adObject != oldWidget.nativeAd.adObject) {
+      _disposeOldAd();
+      _initializeAd();
+    }
+  }
+
+  void _initializeAd() {
+    // Ensure the adObject is of the expected AdMob NativeAd type.
+    if (widget.nativeAd.adObject is admob.NativeAd) {
+      _admobNativeAd = widget.nativeAd.adObject as admob.NativeAd;
+      _isAdLoaded = true;
+    } else {
+      _admobNativeAd = null;
+      _isAdLoaded = false;
+      // Log an error if the adObject is not the expected type.
+      debugPrint(
+        'AdMobNativeAdWidget: Expected admob.NativeAd, but received '
+        '${widget.nativeAd.adObject.runtimeType}. Ad will not be displayed.',
+      );
+    }
+  }
+
+  void _disposeOldAd() {
+    _admobNativeAd?.dispose();
+    _admobNativeAd = null;
+    _isAdLoaded = false;
+  }
+
+  @override
+  void dispose() {
+    _disposeOldAd();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (!_isAdLoaded || _admobNativeAd == null) {
+      // If the ad is not loaded or is of the wrong type, return an empty container.
+      return const SizedBox.shrink();
+    }
+
+    // Use the AdMob SDK's AdWidget to render the native ad.
+    return admob.AdWidget(ad: _admobNativeAd!);
+  }
+}

lib/ads/widgets/widgets.dart

@@ -0,0 +1 @@
+export 'admob_native_ad_widget.dart';

lib/app/view/app.dart

@@ -26,26 +26,26 @@ class App extends StatelessWidget {
     required DataRepository<Source> sourcesRepository,
     required DataRepository<UserAppSettings> userAppSettingsRepository,
     required DataRepository<UserContentPreferences>
-        userContentPreferencesRepository,
+    userContentPreferencesRepository,
     required DataRepository<RemoteConfig> remoteConfigRepository,
     required DataRepository<User> userRepository,
     required KVStorageService kvStorageService,
     required AppEnvironment environment,
     required AdService adService,
     this.demoDataMigrationService,
     super.key,
-  })  : _authenticationRepository = authenticationRepository,
-        _headlinesRepository = headlinesRepository,
-        _topicsRepository = topicsRepository,
-        _countriesRepository = countriesRepository,
-        _sourcesRepository = sourcesRepository,
-        _userAppSettingsRepository = userAppSettingsRepository,
-        _userContentPreferencesRepository = userContentPreferencesRepository,
-        _appConfigRepository = remoteConfigRepository,
-        _userRepository = userRepository,
-        _kvStorageService = kvStorageService,
-        _environment = environment,
-        _adService = adService;
+  }) : _authenticationRepository = authenticationRepository,
+       _headlinesRepository = headlinesRepository,
+       _topicsRepository = topicsRepository,
+       _countriesRepository = countriesRepository,
+       _sourcesRepository = sourcesRepository,
+       _userAppSettingsRepository = userAppSettingsRepository,
+       _userContentPreferencesRepository = userContentPreferencesRepository,
+       _appConfigRepository = remoteConfigRepository,
+       _userRepository = userRepository,
+       _kvStorageService = kvStorageService,
+       _environment = environment,
+       _adService = adService;
 
   final AuthRepository _authenticationRepository;
   final DataRepository<Headline> _headlinesRepository;
@@ -54,7 +54,7 @@ class App extends StatelessWidget {
   final DataRepository<Source> _sourcesRepository;
   final DataRepository<UserAppSettings> _userAppSettingsRepository;
   final DataRepository<UserContentPreferences>
-      _userContentPreferencesRepository;
+  _userContentPreferencesRepository;
   final DataRepository<RemoteConfig> _appConfigRepository;
   final DataRepository<User> _userRepository;
   final KVStorageService _kvStorageService;
@@ -83,10 +83,9 @@ class App extends StatelessWidget {
           BlocProvider(
             create: (context) => AppBloc(
               authenticationRepository: context.read<AuthRepository>(),
-              userAppSettingsRepository:
-                  context.read<DataRepository<UserAppSettings>>(),
-              appConfigRepository:
-                  context.read<DataRepository<RemoteConfig>>(),
+              userAppSettingsRepository: context
+                  .read<DataRepository<UserAppSettings>>(),
+              appConfigRepository: context.read<DataRepository<RemoteConfig>>(),
               userRepository: context.read<DataRepository<User>>(),
               environment: _environment,
               demoDataMigrationService: demoDataMigrationService,