From 2dfb72304bd3995b16dd120a43b89a3d671e40c7 Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Mon, 23 Sep 2024 16:09:31 +0200 Subject: [PATCH 1/3] feat: base implementation for MatomoGlobalObserver --- example/lib/main.dart | 5 ++- lib/matomo_tracker.dart | 2 + lib/src/observers/matomo_global_observer.dart | 45 +++++++++++++++++++ lib/src/observers/matomo_local_observer.dart | 23 ++++++++++ lib/src/traceable_widget_mixin.dart | 11 ++--- test/ressources/utils/testable_app.dart | 4 +- 6 files changed, 82 insertions(+), 8 deletions(-) create mode 100644 lib/src/observers/matomo_global_observer.dart create mode 100644 lib/src/observers/matomo_local_observer.dart diff --git a/example/lib/main.dart b/example/lib/main.dart index 1063d44..b691b16 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -42,7 +42,10 @@ class MyApp extends StatelessWidget { primarySwatch: Colors.blue, ), home: const MyHomePage(title: 'Matomo Example'), - navigatorObservers: [matomoObserver], + navigatorObservers: [ + MatomoGlobalObserver(), + matomoLocalObserver, + ], ); } } diff --git a/lib/matomo_tracker.dart b/lib/matomo_tracker.dart index 83a5c4c..2461c8e 100644 --- a/lib/matomo_tracker.dart +++ b/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'; diff --git a/lib/src/observers/matomo_global_observer.dart b/lib/src/observers/matomo_global_observer.dart new file mode 100644 index 0000000..731182f --- /dev/null +++ b/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> { + /// {@macro matomo_global_observer} + MatomoGlobalObserver({ + MatomoTracker? tracker, + }) : _tracker = tracker ?? MatomoTracker.instance; + + final MatomoTracker _tracker; + + @override + void didPush(Route route, Route? previousRoute) { + super.didPush(route, previousRoute); + _trackPageView(route); + } + + @override + void didPop(Route route, Route? previousRoute) { + super.didPop(route, previousRoute); + _trackPageView(previousRoute); + } + + void _trackPageView(Route? route) { + _tracker.trackPageViewWithName( + actionName: route?.settings.name ?? 'unknown', + ); + } +} diff --git a/lib/src/observers/matomo_local_observer.dart b/lib/src/observers/matomo_local_observer.dart new file mode 100644 index 0000000..bbdf205 --- /dev/null +++ b/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 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>(); diff --git a/lib/src/traceable_widget_mixin.dart b/lib/src/traceable_widget_mixin.dart index 2c79d15..939be02 100644 --- a/lib/src/traceable_widget_mixin.dart +++ b/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>(); - /// Register a [MatomoTracker.trackPageViewWithName] on this widget. @optionalTypeArgs mixin TraceableClientMixin on State @@ -95,13 +96,13 @@ mixin TraceableClientMixin on State 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(); } diff --git a/test/ressources/utils/testable_app.dart b/test/ressources/utils/testable_app.dart index 0b92382..f91ef84 100644 --- a/test/ressources/utils/testable_app.dart +++ b/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], ); } } From 39a0ec2e0463682de2f685bf49fd2f0abede055f Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Mon, 23 Sep 2024 16:20:37 +0200 Subject: [PATCH 2/3] chore: update documentation --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++--- example/lib/main.dart | 2 +- pubspec.yaml | 2 +- 3 files changed, 53 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e5d7c75..a090378 100644 --- a/README.md +++ b/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. diff --git a/example/lib/main.dart b/example/lib/main.dart index b691b16..3195fa0 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -43,8 +43,8 @@ class MyApp extends StatelessWidget { ), home: const MyHomePage(title: 'Matomo Example'), navigatorObservers: [ - MatomoGlobalObserver(), matomoLocalObserver, + MatomoGlobalObserver(), ], ); } diff --git a/pubspec.yaml b/pubspec.yaml index 25ec998..da71b09 100644 --- a/pubspec.yaml +++ b/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 From b64a38ae7c9a4de9f271cec28c5046f13deb0d2a Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Mon, 23 Sep 2024 16:20:58 +0200 Subject: [PATCH 3/3] chore: update doc --- lib/src/observers/matomo_local_observer.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/observers/matomo_local_observer.dart b/lib/src/observers/matomo_local_observer.dart index bbdf205..83206a4 100644 --- a/lib/src/observers/matomo_local_observer.dart +++ b/lib/src/observers/matomo_local_observer.dart @@ -3,7 +3,7 @@ import 'package:flutter/widgets.dart'; /// {@macro matomo_local_observer} @Deprecated( 'Use matomoLocalObserver instead. ' - 'This feature was deprecated in v6.0.0 and will be removed in the next major version.', + 'This feature was deprecated in v6.0.0-dev.1 and will be removed in the next major version.', ) final matomoObserver = matomoLocalObserver;