matomo_tracker

Description:

matomo tracker

Matomo Tracker #









Forked from the package matomo by poitch.
A fully cross-platform wrap of the Matomo tracking client for Flutter, using the Matomo Tracking API.
Summary #

Documentation

Supported Matomo Versions
Getting Started
Using userId
Opting Out
Using Dimensions
Cookieless Tracking
Dispatching


Migration Guide

v5.0.0
v4.0.0
v3.0.0


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.
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
);
copied to clipboard
If you need to use your own Visitor ID, you can pass it at the initialization of MatomoTracker as is:
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
visitorId: '2589631479517535',
);
copied to clipboard
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:
MaterialApp(
// ...
navigatorObservers: [
matomoObserver,
],
);
copied to clipboard
To track views simply add TraceableClientMixin on your State:
class MyHomePage extends StatefulWidget {
const MyHomePage({Key key, this.title}) : super(key: key);

final String title;

@override
_MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> 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
}
copied to clipboard
If you are in a StatelessWidget you can use the TraceableWidget widget:
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!'),
),
),
);
}
}
copied to clipboard
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:
MatomoTracker.instance.trackEvent(
eventInfo: EventInfo(
category: 'eventCategory',
name: 'eventName',
action: 'eventAction',
value: 18,
),
);
copied to clipboard
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:
String userId = auth.currentUser?.email ?? auth.currentUser!.uid;
MatomoTracker.instance.setVisitorUserId(userId);
copied to clipboard
Opting Out #
If you want to offer a way for the user to opt out of analytics, you can use the setOptOut() call.
MatomoTracker.instance.setOptOut(optout: true);
copied to clipboard
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):
MatomoTracker.instance.trackDimensions({
'dimension1': '0.0.1'
});
copied to clipboard
MatomoTracker.instance.trackEvent(
eventInfo: EventInfo(
category: "eventCategory",
action: "eventAction",
name: "eventName",
value: 18,
),
dimensions: {'dimension2':'guest-user'}
);
copied to clipboard
You can similarly track dimensions on Screen views with:
MatomoTracker.instance.trackPageViewWithName(
actionName: "Settings",
path: "/settings",
dimensions: {'dimension1': '0.0.1'}
);
copied to clipboard
The naming of the dimensions is important and explained in more detail in the documentation of trackDimensions.
Cookieless Tracking #
If you want to use cookieless tracking, you can use the cookieless property in the initialize method.
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
cookieless: true,
);
copied to clipboard
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 class for more configuration options.
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
dispatchSettings: const DispatchSettings.persistent(),
);
copied to clipboard
Migration Guide #
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:

MaterialApp(
// ...
navigatorObservers: [
matomoObserver,
],
);
copied to clipboard

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 with the class SharedPrefsStorage, but you can provide your own implementation of LocalStorage to use a different package.
Before #
final myPrefs = await SharedPreferences.getInstance();

await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
prefs: myPrefs,
);
copied to clipboard
After #
class MyLocalStorage implements LocalStorage {
MyLocalStorage();

// ...
}

final myStorage = MyLocalStorage();

await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
localStorage: myStorage,
);
copied to clipboard
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.
await MatomoTracker.instance.initialize(
siteId: siteId,
url: 'https://example.com/matomo.php',
);
copied to clipboard
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







David Serrano Canales