Merge pull request #174 from Floating-Dartists/173-feat-improve-matom…

…oobserver-to-dispense-with-traceableclientmixin

173 feat improve matomoobserver to dispense with traceableclientmixin

README.md

@@ -26,6 +26,7 @@ A fully cross-platform wrap of the Matomo tracking client for Flutter, using the
   - [Cookieless Tracking](#cookieless-tracking)
   - [Dispatching](#dispatching)
 - [Migration Guide](#migration-guide)
+    - [v6.0.0](#v600)
     - [v5.0.0](#v500)
     - [v4.0.0](#v400)
     - [v3.0.0](#v300)
@@ -59,18 +60,39 @@ await MatomoTracker.instance.initialize(
 ```
 Note that this Visitor ID should not be confused with the User ID which is explained below!
 
-Then, for `TraceableClientMixin` and `TraceableWidget` to work, you will have to add `matomoObserver` to your navigatorObservers:
+## Navigator Observers
+
+The package provides you with two ways to track views:
+
+### `MatomoGlobalObserver`
+
+To track views globally, you can add the `MatomoGlobalObserver` to your `navigatorObservers`:
 
 ```dart
 MaterialApp(
     // ...
     navigatorObservers: [
-        matomoObserver,
+        MatomoGlobalObserver(),
     ],
 );
 ```
 
-To track views simply add `TraceableClientMixin` on your `State`:
+And your views will be tracked automatically for each route change.
+
+### `TraceableClientMixin` & `TraceableWidget`
+
+Those are used if you want to only track some specific widgets. First, you will have to add `matomoLocalObserver` to your `navigatorObservers`:
+
+```dart
+MaterialApp(
+    // ...
+    navigatorObservers: [
+        matomoLocalObserver,
+    ],
+);
+```
+
+To track views on a `StatefulWidget` simply add `TraceableClientMixin` on your `State`:
 
 ```dart
 class MyHomePage extends StatefulWidget {
@@ -227,6 +249,32 @@ await MatomoTracker.instance.initialize(
 
 # Migration Guide
 
+## v6.0.0
+
+* `matomoObserver` has been deprecated and will be removed in the next major version. You should now use `matomoLocalObserver`.
+
+### Before
+
+```dart
+MaterialApp(
+    // ...
+    navigatorObservers: [
+        matomoObserver,
+    ],
+);
+```
+
+### After
+
+```dart
+MaterialApp(
+    // ...
+    navigatorObservers: [
+        matomoLocalObserver,
+    ],
+);
+```
+
 ## v5.0.0
 
 * `Session` class and its related properties `firstVisit`, `lastVisit` and `visitCount` have been removed as they were not used since Matomo 4.0.0.

example/lib/main.dart

@@ -42,7 +42,10 @@ class MyApp extends StatelessWidget {
         primarySwatch: Colors.blue,
       ),
       home: const MyHomePage(title: 'Matomo Example'),
-      navigatorObservers: [matomoObserver],
+      navigatorObservers: [
+        matomoLocalObserver,
+        MatomoGlobalObserver(),
+      ],
     );
   }
 }

lib/matomo_tracker.dart

@@ -10,6 +10,8 @@ export 'src/exceptions.dart';
 export 'src/local_storage/local_storage.dart';
 export 'src/logger/log_record.dart' show Level;
 export 'src/matomo.dart';
+export 'src/observers/matomo_global_observer.dart';
+export 'src/observers/matomo_local_observer.dart';
 export 'src/performance_info.dart';
 export 'src/traceable_widget.dart';
 export 'src/traceable_widget_mixin.dart';

lib/src/observers/matomo_global_observer.dart

@@ -0,0 +1,45 @@
+import 'package:flutter/widgets.dart';
+import 'package:matomo_tracker/matomo_tracker.dart';
+
+/// {@template matomo_global_observer}
+/// A [RouteObserver] that will track all the route navigation events in Matomo.
+///
+/// You can specify a custom [MatomoTracker] instance with the `tracker`
+/// parameter. (defaults to [MatomoTracker.instance] if not provided)
+///
+/// ### Example
+///
+/// ```dart
+/// MaterialApp(
+///   navigatorObservers: [
+///     MatomoGlobalObserver(),
+///   ],
+/// );
+/// ```
+/// {@endtemplate}
+class MatomoGlobalObserver extends RouteObserver<PageRoute<dynamic>> {
+  /// {@macro matomo_global_observer}
+  MatomoGlobalObserver({
+    MatomoTracker? tracker,
+  }) : _tracker = tracker ?? MatomoTracker.instance;
+
+  final MatomoTracker _tracker;
+
+  @override
+  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    super.didPush(route, previousRoute);
+    _trackPageView(route);
+  }
+
+  @override
+  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    super.didPop(route, previousRoute);
+    _trackPageView(previousRoute);
+  }
+
+  void _trackPageView(Route<dynamic>? route) {
+    _tracker.trackPageViewWithName(
+      actionName: route?.settings.name ?? 'unknown',
+    );
+  }
+}

lib/src/observers/matomo_local_observer.dart

@@ -0,0 +1,23 @@
+import 'package:flutter/widgets.dart';
+
+/// {@macro matomo_local_observer}
+@Deprecated(
+  'Use matomoLocalObserver instead. '
+  'This feature was deprecated in v6.0.0-dev.1 and will be removed in the next major version.',
+)
+final matomoObserver = matomoLocalObserver;
+
+/// {@template matomo_local_observer}
+/// A [RouteObserver] that will track navigation events in Matomo from a widget
+/// that uses `TraceableWidgetMixin`.
+/// {@endtemplate}
+///
+/// ### Example
+///
+/// ```dart
+/// MaterialApp(
+///   navigatorObservers: [
+///     matomoLocalObserver,
+///   ],
+/// );
+final matomoLocalObserver = RouteObserver<ModalRoute<void>>();

lib/src/traceable_widget_mixin.dart

@@ -1,9 +1,10 @@
 import 'package:flutter/material.dart';
-import 'package:matomo_tracker/matomo_tracker.dart';
+import 'package:matomo_tracker/src/campaign.dart';
+import 'package:matomo_tracker/src/matomo.dart';
+import 'package:matomo_tracker/src/observers/matomo_local_observer.dart';
+import 'package:matomo_tracker/src/performance_info.dart';
 import 'package:matomo_tracker/utils/random_alpha_numeric.dart';
 
-final matomoObserver = RouteObserver<ModalRoute<void>>();
-
 /// Register a [MatomoTracker.trackPageViewWithName] on this widget.
 @optionalTypeArgs
 mixin TraceableClientMixin<T extends StatefulWidget> on State<T>
@@ -95,13 +96,13 @@ mixin TraceableClientMixin<T extends StatefulWidget> on State<T>
 
     final route = ModalRoute.of(context);
     if (route != null) {
-      matomoObserver.subscribe(this, route);
+      matomoLocalObserver.subscribe(this, route);
     }
   }
 
   @override
   void dispose() {
-    matomoObserver.unsubscribe(this);
+    matomoLocalObserver.unsubscribe(this);
     super.dispose();
   }
 

pubspec.yaml

@@ -1,7 +1,7 @@
 name: matomo_tracker
 description: A fully cross-platform wrap of the Matomo tracking client for
   Flutter, using the Matomo API.
-version: 5.1.0
+version: 6.0.0-dev.1
 homepage: https://github.com/Floating-Dartists/matomo-tracker
 repository: https://github.com/Floating-Dartists/matomo-tracker
 issue_tracker: https://github.com/Floating-Dartists/matomo-tracker/issues

test/ressources/utils/testable_app.dart

@@ -1,5 +1,5 @@
 import 'package:flutter/material.dart';
-import 'package:matomo_tracker/src/traceable_widget_mixin.dart';
+import 'package:matomo_tracker/src/observers/matomo_local_observer.dart';
 
 class TestableApp extends StatelessWidget {
   const TestableApp({
@@ -13,7 +13,7 @@ class TestableApp extends StatelessWidget {
   Widget build(BuildContext context) {
     return MaterialApp(
       home: child,
-      navigatorObservers: [matomoObserver],
+      navigatorObservers: [matomoLocalObserver],
     );
   }
 }