Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Floating-Dartists/matomo-tracker
A fully cross-platform wrap of the Matomo tracking client for Flutter, using the Matomo API.
https://github.com/Floating-Dartists/matomo-tracker
dart flutter matomo matomo-plugin matomo-tracking
Last synced: 5 days ago
JSON representation
A fully cross-platform wrap of the Matomo tracking client for Flutter, using the Matomo API.
- Host: GitHub
- URL: https://github.com/Floating-Dartists/matomo-tracker
- Owner: Floating-Dartists
- License: mit
- Created: 2022-04-12T12:34:54.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T07:36:49.000Z (7 months ago)
- Last Synced: 2024-04-02T13:09:03.567Z (7 months ago)
- Topics: dart, flutter, matomo, matomo-plugin, matomo-tracking
- Language: Dart
- Homepage: https://pub.dev/packages/matomo_tracker
- Size: 681 KB
- Stars: 22
- Watchers: 2
- Forks: 22
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Matomo Tracker
[](https://pub.dev/packages/matomo_tracker)
[](https://matomo.org/integrate/)
[](https://github.com/Floating-Dartists/matomo-tracker/blob/main/LICENSE)
[](https://coveralls.io/github/Floating-Dartists/matomo-tracker?branch=main)
Forked from the package [matomo](https://pub.dev/packages/matomo) by [poitch](https://github.com/poitch).
A fully cross-platform wrap of the Matomo tracking client for Flutter, using the [Matomo Tracking API](https://developer.matomo.org/api-reference/tracking-api).
# Summary
- [Documentation](#documentation)
- [Supported Matomo Versions](#supported-matomo-versions)
- [Getting Started](#getting-started)
- [Using userId](#using-userid)
- [Opting Out](#opting-out)
- [Using Dimensions](#using-dimensions)
- [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)
- [Contributors](#contributors)
# Documentation
## Supported Matomo Versions
This package (matomo_tracker v5.0.0) currently supports Matomo 4.X up to Matomo 5.X.
## Getting Started
As early as possible in your application, you need to configure the Matomo Tracker to pass the URL endpoint of your instance and your Site ID.
```dart
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
);
```
If you need to use your own Visitor ID, you can pass it at the initialization of MatomoTracker as is:
```dart
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
visitorId: '2589631479517535',
);
```
Note that this Visitor ID should not be confused with the User ID which is explained below!
## 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: [
MatomoGlobalObserver(),
],
);
```
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 {
const MyHomePage({Key key, this.title}) : super(key: key);
final String title;
@override
_MyHomePageState createState() => _MyHomePageState();
}
class _MyHomePageState extends State with TraceableClientMixin {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
),
body: Center(
child: Text('Hello World!'),
),
);
}
@override
String get actionName => 'Created HomePage'; // optional
@override
String get path => '/home'; // optional
}
```
If you are in a `StatelessWidget` you can use the `TraceableWidget` widget:
```dart
class MyHomePage extends StatelessWidget {
const MyHomePage({Key key, this.title}) : super(key: key);
final String title;
@override
Widget build(BuildContext context) {
return TraceableWidget(
actionName: 'Created HomePage', // optional
path: '/home', // optional
child: Scaffold(
appBar: AppBar(
title: Text(title),
),
body: Center(
child: Text('Hello World!'),
),
),
);
}
}
```
You can also optionally call directly `trackPageView` or `trackPageViewWithName` to track a view.
For tracking goals and, events call `trackGoal` and `trackEvent` respectively.
A value can be passed for events:
```dart
MatomoTracker.instance.trackEvent(
eventInfo: EventInfo(
category: 'eventCategory',
name: 'eventName',
action: 'eventAction',
value: 18,
),
);
```
## Using userId
If your application uses authentication and you wish to have your visitors including their specific identity to Matomo, you can use the Visitor property userId with any unique identifier from your back-end, by calling the setVisitorUserId() method. Here's an example on how to do it with Firebase:
```dart
String userId = auth.currentUser?.email ?? auth.currentUser!.uid;
MatomoTracker.instance.setVisitorUserId(userId);
```
## Opting Out
If you want to offer a way for the user to opt out of analytics, you can use the `setOptOut()` call.
```dart
MatomoTracker.instance.setOptOut(optout: true);
```
## Using Dimensions
If you want to track Visit or Action dimensions you can either use the `trackDimensions` (if
it's a Visit level dimension) or provide data in the optional dimensions param of `trackEvent`
(if it's an Action level dimension):
```dart
MatomoTracker.instance.trackDimensions({
'dimension1': '0.0.1'
});
```
```dart
MatomoTracker.instance.trackEvent(
eventInfo: EventInfo(
category: "eventCategory",
action: "eventAction",
name: "eventName",
value: 18,
),
dimensions: {'dimension2':'guest-user'}
);
```
You can similarly track dimensions on Screen views with:
```dart
MatomoTracker.instance.trackPageViewWithName(
actionName: "Settings",
path: "/settings",
dimensions: {'dimension1': '0.0.1'}
);
```
The naming of the dimensions is important and explained in more detail in the documentation of [`trackDimensions`](https://pub.dev/documentation/matomo_tracker/latest/matomo_tracker/MatomoTracker/trackDimensions.html).
## Cookieless Tracking
If you want to use cookieless tracking, you can use the `cookieless` property in the `initialize` method.
```dart
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
cookieless: true,
);
```
When using cookieless tracking, the user_id won't be sent or saved locally.
## Dispatching
Actions logged are not send to Matomo immediately, but are queued for a configurable duration (defaulting to 10 seconds) before beeing send in batch. A user could terminate your app while there are still undispatched actions in the queue, which by default would be lost. The queue can be configured to be persistent so that such actions would then be send on the next app launch. See the [`DispatchSettings`](https://pub.dev/documentation/matomo_tracker/latest/matomo_tracker/DispatchSettings-class.html) class for more configuration options.
```dart
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
dispatchSettings: const DispatchSettings.persistent(),
);
```
# 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.
* `LocalStorage` methods `getFirstVisit`, `setFirstVisit`, `getVisitCount` and `setVisitCount` have been removed accordingly.
* `siteId` is now a `String` instead of an `int`
## v4.0.0
* `trackScreen` was renamed to `trackPageView` and `trackScreenWithName` to `trackPageViewWithName`.
* `screenId` and `widgetId` were renamed to `pvId`.
* `userId` was renamed to `uid`.
* `traceName` and `widgetName` were renamed to `actionName`.
* `traceTitle` was renamed to `eventName`.
* `forcedId` property has been removed as it was never used. You should rely on the user ID instead.
* An object of type `EventInfo` has been added, it has the following properties: `category`, `action`, `name` and `value`, use it instead of passing the event name, action and value as separate parameters.
* For `TraceableClientMixin` and `TraceableWidget` to work you will have to add the `matomoObserver` to your `MaterialApp` or `WidgetsApp`:
```dart
MaterialApp(
// ...
navigatorObservers: [
matomoObserver,
],
);
```
* `MatomoEvent` has been renamed to `MatomoAction`
* `trackPageView` positional parameter `context` is now a named parameter
* `trackGoal` positional parameter `goalId` is now a named parameter: `id`
* `trackDimensions` positional parameter `dimensions` is now a named parameter
* `trackCartUpdate` positional parameters `trackingOrderItems`, `subTotal`, `taxAmount`, `shippingCost` and `discountAmount` are now named parameters
* `trackOrder` positional parameters `orderId` (now `id`), `trackingOrderItems`, `revenue` (also became a `double`), `subTotal`, `taxAmount`, `shippingCost` and `discountAmount` are now named parameters
* `trackOutlink` positional parameter `link` is now a named required parameter (also changed the type to `String`)
## v3.0.0
Now the `initialize()` method takes a `LocalStorage? localStorage` instead of a `SharedPreferences? prefs` as its parameter to override the persistent data implementation.
By default it will use an implementation of [shared_preferences](https://pub.dev/packages/shared_preferences) with the class `SharedPrefsStorage`, but you can provide your own implementation of `LocalStorage` to use a different package.
### Before
```dart
final myPrefs = await SharedPreferences.getInstance();
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
prefs: myPrefs,
);
```
### After
```dart
class MyLocalStorage implements LocalStorage {
MyLocalStorage();
// ...
}
final myStorage = MyLocalStorage();
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
localStorage: myStorage,
);
```
**Note that if you weren't using a custom instance of `SharedPreferences` before, you don't need to change anything. The default behavior still works.**
```dart
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
);
```
# Contributors
Guillaume Roux
Null
Pierre Monier
Jêrôme Poichet
Marvin Möltgen
Krille-chan
Scolnet
Meï
Null
Null
Paula Petcu
Chris Tomlinson
Null
Johann Schramm
Lsaudon
Peter Leibiger
Zvi Karp
Timothy Freebern II
Null
Gabriel Costache
Herbert Poul
Hitesh C
Julian Bissekkou
Lukas Lihotzki
