Merge pull request #80 from flutter-news-app-full-source-code/Implementing-an-Extensible-Ad-Network-Service

Implementing an extensible ad network service

Author: fulleni

README.md

@@ -73,6 +73,12 @@ 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

android/app/src/main/AndroidManifest.xml

@@ -38,6 +38,11 @@
         <meta-data
             android:name="flutterEmbedding"
             android:value="2" />
+
+        <!-- TODO(fulleni): Replace with your real AdMob App ID -->
+        <meta-data
+            android:name="com.google.android.gms.ads.APPLICATION_ID"
+            android:value="ca-app-pub-3940256099942544~3347511713"/>
     </application>
     <!-- Required to query activities that can process text, see:
          https://developer.android.com/training/package-visibility and

lib/ads/ad_provider.dart

@@ -0,0 +1,28 @@
+import 'package:google_mobile_ads/google_mobile_ads.dart';
+
+/// {@template ad_provider}
+/// An abstract class defining the interface for any ad network provider.
+///
+/// This abstraction allows the application to integrate with different
+/// ad networks (e.g., AdMob, Meta Audience Network) through a common API,
+/// promoting extensibility and decoupling.
+/// {@endtemplate}
+abstract class AdProvider {
+  /// {@macro ad_provider}
+  const AdProvider();
+
+  /// Initializes the ad network SDK.
+  ///
+  /// This method should be called once at application startup.
+  /// It handles any necessary setup for the specific ad network.
+  Future<void> initialize();
+
+  /// Loads a native ad.
+  ///
+  /// Returns a [NativeAd] object if an ad is successfully loaded,
+  /// otherwise returns `null`.
+  Future<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

@@ -0,0 +1,59 @@
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/ad_provider.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/models/ad_feed_item.dart';
+import 'package:logging/logging.dart';
+import 'package:uuid/uuid.dart';
+
+/// {@template ad_service}
+/// A service responsible for managing and providing ads to the application.
+///
+/// This service acts as an intermediary between the application's UI/logic
+/// and the underlying ad network providers (e.g., AdMob). It handles
+/// requesting ads and wrapping them in a generic [AdFeedItem] for use
+/// in the feed.
+/// {@endtemplate}
+class AdService {
+  /// {@macro ad_service}
+  ///
+  /// 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');
+
+  final AdProvider _adProvider;
+  final Logger _logger;
+  final Uuid _uuid = const Uuid();
+
+  /// Initializes the underlying ad provider.
+  ///
+  /// This should be called once at application startup.
+  Future<void> initialize() async {
+    _logger.info('Initializing AdService...');
+    await _adProvider.initialize();
+    _logger.info('AdService initialized.');
+  }
+
+  /// Retrieves a loaded native ad wrapped as an [AdFeedItem].
+  ///
+  /// This method delegates the ad loading to the injected [AdProvider].
+  /// If an ad is successfully loaded, it's wrapped in an [AdFeedItem]
+  /// with a unique ID.
+  ///
+  /// Returns an [AdFeedItem] if an ad is available, otherwise `null`.
+  Future<AdFeedItem?> getAd() async {
+    _logger.info('Requesting native ad from AdProvider...');
+    try {
+      final nativeAd = await _adProvider.loadNativeAd();
+      if (nativeAd != null) {
+        _logger.info('Native ad successfully loaded and wrapped.');
+        return AdFeedItem(id: _uuid.v4(), nativeAd: nativeAd);
+      } else {
+        _logger.info('No native ad loaded by AdProvider.');
+        return null;
+      }
+    } catch (e) {
+      _logger.severe('Error getting ad from AdProvider: $e');
+      return null;
+    }
+  }
+}

lib/ads/admob_ad_provider.dart

@@ -0,0 +1,119 @@
+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:logging/logging.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.
+/// {@endtemplate}
+class AdMobAdProvider implements AdProvider {
+  /// {@macro admob_ad_provider}
+  AdMobAdProvider({Logger? logger}) : _logger = logger ?? Logger('AdMobAdProvider');
+
+  final Logger _logger;
+
+  /// The AdMob Native Ad Unit ID for Android.
+  ///
+  /// This should be replaced with your production Ad Unit ID.
+  /// For testing, use `ca-app-pub-3940256099942544/2247696110`.
+  static const String _androidNativeAdUnitId =
+      'ca-app-pub-3940256099942544/2247696110';
+
+  /// The AdMob Native Ad Unit ID for iOS.
+  ///
+  /// This should be replaced with your production Ad Unit ID.
+  /// For testing, use `ca-app-pub-3940256099942544/3986624511`.
+  static const String _iosNativeAdUnitId =
+      'ca-app-pub-3940256099942544/3986624511';
+
+  /// The AdMob Native Ad Unit ID for Web.
+  ///
+  /// AdMob does not officially support native ads on web. This is a placeholder.
+  /// For testing, use `ca-app-pub-3940256099942544/2247696110` (Android test ID).
+  static const String _webNativeAdUnitId =
+      'ca-app-pub-3940256099942544/2247696110';
+
+  /// Returns the appropriate native ad unit ID based on the platform.
+  String get _nativeAdUnitId {
+    if (kIsWeb) {
+      return _webNativeAdUnitId;
+    } else if (defaultTargetPlatform == TargetPlatform.android) {
+      return _androidNativeAdUnitId;
+    } else if (defaultTargetPlatform == TargetPlatform.iOS) {
+      return _iosNativeAdUnitId;
+    }
+    return ''; // Fallback for unsupported platforms
+  }
+
+  @override
+  Future<void> initialize() async {
+    _logger.info('Initializing Google Mobile Ads SDK...');
+    try {
+      await MobileAds.instance.initialize();
+      _logger.info('Google Mobile Ads SDK initialized successfully.');
+    } catch (e) {
+      _logger.severe('Failed to initialize Google Mobile Ads SDK: $e');
+      // TODO(fulleni): Depending on requirements, you might want to rethrow or handle this more gracefully.
+      // For now, we log and continue, as ad loading might still work in some cases.
+    }
+  }
+
+  @override
+  Future<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 ad = NativeAd(
+      adUnitId: _nativeAdUnitId,
+      factoryId: 'listTile', // This ID must match a factory in your native code
+      request: const AdRequest(),
+      listener: NativeAdListener(
+        onAdLoaded: (ad) {
+          _logger.info('Native Ad loaded successfully.');
+          completer.complete(ad as NativeAd);
+        },
+        onAdFailedToLoad: (ad, error) {
+          _logger.severe('Native Ad failed to load: $error');
+          ad.dispose();
+          completer.complete(null);
+        },
+        onAdClicked: (ad) {
+          _logger.info('Native Ad clicked.');
+        },
+        onAdImpression: (ad) {
+          _logger.info('Native Ad impression recorded.');
+        },
+        onAdClosed: (ad) {
+          _logger.info('Native Ad closed.');
+          ad.dispose();
+        },
+        onAdOpened: (ad) {
+          _logger.info('Native Ad opened.');
+        },
+        onAdWillDismissScreen: (ad) {
+          _logger.info('Native Ad will dismiss screen.');
+        },
+      ),
+    );
+
+    try {
+      await ad.load();
+    } catch (e) {
+      _logger.severe('Error during native ad load: $e');
+      completer.complete(null);
+    }
+
+    return completer.future;
+  }
+}

lib/ads/models/ad_feed_item.dart

@@ -0,0 +1,32 @@
+import 'package:core/core.dart';
+import 'package:equatable/equatable.dart';
+import 'package:google_mobile_ads/google_mobile_ads.dart';
+
+/// {@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
+/// 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');
+
+  /// 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.
+  ///
+  /// This object contains the actual ad content and is ready for display.
+  final NativeAd nativeAd;
+
+  @override
+  List<Object?> get props => [id, nativeAd, type];
+}

lib/app/view/app.dart

@@ -4,6 +4,7 @@ import 'package:data_repository/data_repository.dart';
 import 'package:flex_color_scheme/flex_color_scheme.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
+import 'package:flutter_news_app_mobile_client_full_source_code/ads/ad_service.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/bloc/app_bloc.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/config/app_environment.dart';
 import 'package:flutter_news_app_mobile_client_full_source_code/app/services/app_status_service.dart';
@@ -25,24 +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;
+  })  : _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;
@@ -51,11 +54,12 @@ 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;
   final AppEnvironment _environment;
+  final AdService _adService;
   final DemoDataMigrationService? demoDataMigrationService;
 
   @override
@@ -72,15 +76,17 @@ class App extends StatelessWidget {
         RepositoryProvider.value(value: _appConfigRepository),
         RepositoryProvider.value(value: _userRepository),
         RepositoryProvider.value(value: _kvStorageService),
+        RepositoryProvider.value(value: _adService),
       ],
       child: MultiBlocProvider(
         providers: [
           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,
@@ -103,6 +109,7 @@ class App extends StatelessWidget {
           appConfigRepository: _appConfigRepository,
           userRepository: _userRepository,
           environment: _environment,
+          adService: _adService,
         ),
       ),
     );
@@ -121,6 +128,7 @@ class _AppView extends StatefulWidget {
     required this.appConfigRepository,
     required this.userRepository,
     required this.environment,
+    required this.adService,
   });
 
   final AuthRepository authenticationRepository;
@@ -133,6 +141,7 @@ class _AppView extends StatefulWidget {
   final DataRepository<RemoteConfig> appConfigRepository;
   final DataRepository<User> userRepository;
   final AppEnvironment environment;
+  final AdService adService;
 
   @override
   State<_AppView> createState() => _AppViewState();
@@ -174,6 +183,7 @@ class _AppViewState extends State<_AppView> {
       remoteConfigRepository: widget.appConfigRepository,
       userRepository: widget.userRepository,
       environment: widget.environment,
+      adService: widget.adService,
     );
 
     // Removed Dynamic Link Initialization