Repository files navigation

Forked from the packagematomo bypoitch.

A fully cross-platform wrap of the Matomo tracking client for Flutter, using theMatomo Tracking API.

• Documentation
  • Supported Matomo Versions
  • Getting Started
  • Using userId
  • Opting Out
  • Using Dimensions
  • Cookieless Tracking
  • Dispatching
• Migration Guide
  • v6.0.0
  • v5.0.0
  • v4.0.0
  • v3.0.0
• Contributors

This package (matomo_tracker v5.0.0) currently supports Matomo 4.X up to Matomo 5.X.

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.

awaitMatomoTracker.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:

awaitMatomoTracker.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!

The package provides you with two ways to track views:

To track views globally, you can add theMatomoGlobalObserver to yournavigatorObservers:

MaterialApp(// ...    navigatorObservers: [MatomoGlobalObserver(),    ],);

And your views will be tracked automatically for each route change.

Those are used if you want to only track some specific widgets. First, you will have to addmatomoLocalObserver to yournavigatorObservers:

MaterialApp(// ...    navigatorObservers: [        matomoLocalObserver,    ],);

To track views on aStatefulWidget simply addTraceableClientMixin on yourState:

classMyHomePageextendsStatefulWidget {constMyHomePage({Key key,this.title}):super(key: key);finalString title;@override_MyHomePageStatecreateState()=>_MyHomePageState();}class_MyHomePageStateextendsState<MyHomePage>withTraceableClientMixin {@overrideWidgetbuild(BuildContext context) {returnScaffold(      appBar:AppBar(        title:Text(widget.title),      ),      body:Center(        child:Text('Hello World!'),      ),    );  }@overrideStringget actionName=>'Created HomePage';// optional@overrideStringget path=>'/home';// optional}

If you are in aStatelessWidget you can use theTraceableWidget widget:

classMyHomePageextendsStatelessWidget {constMyHomePage({Key key,this.title}):super(key: key);finalString title;@overrideWidgetbuild(BuildContext context) {returnTraceableWidget(      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 directlytrackPageView ortrackPageViewWithName to track a view.

For tracking goals and, events calltrackGoal andtrackEvent respectively.

A value can be passed for events:

MatomoTracker.instance.trackEvent(    eventInfo:EventInfo(        category:'eventCategory',        name:'eventName',        action:'eventAction',        value:18,    ),);

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);

If you want to offer a way for the user to opt out of analytics, you can use thesetOptOut() call.

MatomoTracker.instance.setOptOut(optout:true);

If you want to track Visit or Action dimensions you can either use thetrackDimensions (ifit's a Visit level dimension) or provide data in the optional dimensions param oftrackEvent(if it's an Action level dimension):

MatomoTracker.instance.trackDimensions({'dimension1':'0.0.1'});

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:

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 oftrackDimensions.

If you want to use cookieless tracking, you can use thecookieless property in theinitialize method.

awaitMatomoTracker.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.

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 theDispatchSettings class for more configuration options.

awaitMatomoTracker.instance.initialize(    siteId: siteId,    url:'https://example.com/matomo.php',    dispatchSettings:constDispatchSettings.persistent(),);

• matomoObserver has been deprecated and will be removed in the next major version. You should now usematomoLocalObserver.

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

MaterialApp(// ...    navigatorObservers: [        matomoLocalObserver,    ],);

• Session class and its related propertiesfirstVisit,lastVisit andvisitCount have been removed as they were not used since Matomo 4.0.0.
• LocalStorage methodsgetFirstVisit,setFirstVisit,getVisitCount andsetVisitCount have been removed accordingly.
• siteId is now aString instead of anint

• trackScreen was renamed totrackPageView andtrackScreenWithName totrackPageViewWithName.
• screenId andwidgetId were renamed topvId.
• userId was renamed touid.
• traceName andwidgetName were renamed toactionName.
• traceTitle was renamed toeventName.
• forcedId property has been removed as it was never used. You should rely on the user ID instead.
• An object of typeEventInfo has been added, it has the following properties:category,action,name andvalue, use it instead of passing the event name, action and value as separate parameters.
• ForTraceableClientMixin andTraceableWidget to work you will have to add thematomoObserver to yourMaterialApp orWidgetsApp:

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

• MatomoEvent has been renamed toMatomoAction
• trackPageView positional parametercontext is now a named parameter
• trackGoal positional parametergoalId is now a named parameter:id
• trackDimensions positional parameterdimensions is now a named parameter
• trackCartUpdate positional parameterstrackingOrderItems,subTotal,taxAmount,shippingCost anddiscountAmount are now named parameters
• trackOrder positional parametersorderId (nowid),trackingOrderItems,revenue (also became adouble),subTotal,taxAmount,shippingCost anddiscountAmount are now named parameters
• trackOutlink positional parameterlink is now a named required parameter (also changed the type toString)

Now theinitialize() method takes aLocalStorage? localStorage instead of aSharedPreferences? prefs as its parameter to override the persistent data implementation.

By default it will use an implementation ofshared_preferences with the classSharedPrefsStorage, but you can provide your own implementation ofLocalStorage to use a different package.

final myPrefs=awaitSharedPreferences.getInstance();awaitMatomoTracker.instance.initialize(    siteId: siteId,    url:'https://example.com/matomo.php',    prefs: myPrefs,);

classMyLocalStorageimplementsLocalStorage {MyLocalStorage();// ...}final myStorage=MyLocalStorage();awaitMatomoTracker.instance.initialize(    siteId: siteId,    url:'https://example.com/matomo.php',    localStorage: myStorage,);

Note that if you weren't using a custom instance ofSharedPreferences before, you don't need to change anything. The default behavior still works.

awaitMatomoTracker.instance.initialize(    siteId: siteId,    url:'https://example.com/matomo.php',);

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
Sean Kiluk	David Serrano Canales