search

lcuis / matomo_forever

A perennial Dart plugin to send data to a Matomo server with a Flutter example app.
MIT License
6 stars 2 forks source link
dart flutter flutter-plugin matomo

readme

matomo_forever

A perennial Dart plugin to send data to a Matomo server with a Flutter example app.

This plugin is based on the Matomo HTTP tracking API documentation.

Why matomo_forever?

Matomo is a free, open source, complete, reliable, stable and flexible solution to collect and analyze app and web usages. This can be achieved through a Matomo cloud solution (paid) or through a server on premises.

At the time those lines are written, 2 plugins are proposed on pub.dev for Matomo. They both suffered the following:

matomo_forever has a simpler implementation that provides higher flexibility and sustainability. For example, it supports:

Platforms

This plugin has been successfully tested on Android, iOS, Linux, MacOS and Chrome. It is expected to work fine on Windows.

Examples

An example project app is included in the main project under the example folder. This example app is a good way to interact with a Matomo server as a client.

matomo_forever example app screenshot

Demonstration

The following builds of the example app are available from CI/CD:

Also, the example app is available from a browser directly here. To see it work, you may have to disable your ad-blocker.

Code

Plugin usage

Add to your pubspec.yaml in the dependencies section:

  matomo_forever:

Get packages with command:

flutter packages get

Import:

import 'package:matomo_forever/matomo_forever.dart';
Init

Call the init static method to initialize the plugin:

MatomoForever.init(
        siteUrl,
        idSite,
        id: id,
        apiV: apiV,
        rec: rec,
        method: MatomoForeverMethod.post,
        bulkSize: bulkSize,
        tokenAuth: tokenAuth,
        headers: headers,
        persistentParameters: persistentParameters,
      );

Where:

Track

Track calling the track static method:

bool result = await MatomoForever.track(
    actionName,
    url: url,
    rand: rand,
    urlRef: urlRef,
    cvar: cvar,
    idVc: idVc,
    viewTs: viewTs,
    idTs: idTs,
    rcn: rcn,
    rck: rck,
    res: res,
    h: h,
    m: m,
    s: s,
    fla: fla,
    java: java,
    dir: dir,
    qt: qt,
    realp: realp,
    pdf: pdf,
    wma: wma,
    gears: gears,
    ag: ag,
    cookie: cookie,
    ua: ua,
    lang: lang,
    uid: uid,
    cid: cid,
    newVisit: newVisit,
    dimension0: dimension0,
    dimension1: dimension1,
    dimension2: dimension2,
    dimension3: dimension3,
    dimension4: dimension4,
    dimension5: dimension5,
    dimension6: dimension6,
    dimension7: dimension7,
    dimension8: dimension8,
    dimension9: dimension9,
    dimension10: dimension10,
    link: link,
    download: download,
    search: search,
    searchCat: searchCat,
    searchCount: searchCount,
    pvId: pvId,
    idGoal: idGoal,
    revenue: revenue,
    gtMs: gtMs,
    cs: cs,
    ca: ca,
    pfNet: pfNet,
    pfSrv: pfSrv,
    pfTfr: pfTfr,
    pfDm1: pfDm1,
    pfDm2: pfDm2,
    pfOnl: pfOnl,
    eC: eC,
    eA: eA,
    eN: eN,
    eV: eV,
    cN: cN,
    cP: cP,
    cT: cT,
    cId: cId,
    ecId: ecId,
    ecItems: ecItems,
    ecSt: ecSt,
    ecTx: ecTx,
    ecSh: ecSh,
    ecDt: ecDt,
    ects: ects,
    cip: cip,
    cdt: cdt,
    country: country,
    region: region,
    city: city,
    lat: lat,
    long: long,
    maId: maId,
    maRe: maRe,
    maMt: maMt,
    maTi: maTi,
    maPn: maPn,
    maSt: maSt,
    maLe: maLe,
    maPs: maPs,
    maTtp: maTtp,
    maW: maW,
    maH: maH,
    maFs: maFs,
    maSe: maSe,
    customData: customData,
);

Where:

Send data

Alternatively to calling the track method, one can call the sendDataOrBulk method which takes a simpler Map as a parameter.

bool result = await MatomoForever.sendDataOrBulk(
    addedData,
);

Where:

Send the bulk

When sending in bulks (bulkSize > 0), the bulk data can be pushed by calling the sendQueue method:

bool result = await MatomoForever.sendQueue();

Permissions

Communication with a Matomo server requires internet access for Android and MacOS.

Permissions on Android

Add this to your android/app/src/main/AndroidManifest.xml <manifest>:

    <uses-permission android:name="android.permission.INTERNET" />
Permissions on MacOS

Add this to your macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements files:

    <key>com.apple.security.network.client</key>
    <true/>

Feature requests/comments/questions/bugs

Feel free to log your feature requests/comments/questions/bugs here: https://github.com/lcuis/matomo_forever/issues

Contributions

I would be happy to merge pull request proposals provided that:

Contributions and forks are very welcome!

In your pull request, feel free to add your line in the contributors section below:

Contributors

CI/CD

Continuous integration/deployment status: CI-CD