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
Migration Guide
- v4.0.0
- v3.0.0
Contributors

Documentation #

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

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

Note that this Visitor ID should not be confused with the User ID which is explained below!

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
}

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!'),
        ),
      ),
    );
  }
}

You can also optionally call directly trackScreen or trackScreenWithName 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,
    ),
);

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

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

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

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.trackScreenWithName(
    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.

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

When using cookieless tracking, neither the user_id nor the first_visit will be sent or saved locally.

Migration Guide #

v4.0.0 #

forcedId property has been removed as it was never used. You should rely on the user ID instead.
Occurences of userId have been renamed to uid.
Occurences of traceName and widgetName have been renamed to actionName.
Occurences of traceTitle have been renamed to eventName.
Occurences of widgetId have been renamed to pvId.
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: [
        MatomoTracker.matomoObserver,
    ],
);

MatomoEvent has been renamed to MatomoAction

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

After #

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.

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

Contributors #

_{Guillaume Roux}	_{Pierre Monier}	_{Jêrôme Poichet}	_{Marvin Möltgen}	_Krille-chan	_Scolnet
_Null	_Null	_Meï	_{Paula Petcu}	_{Chris Tomlinson}	_{Johann Schramm}
_Lsaudon	_Null	_Null	_{Lukas Lihotzki}	_{David Serrano Canales}