Getting started

Our Flutter SDK lets you collect user data from mobile apps. It contains over 40 methods that make it easy to track screen views, goals, ecommerce orders and more. To get started, you need to set up your account in Piwik PRO, install our library and set up the tracker.

Set up Piwik PRO

Before you install our library for Flutter, you need to set up Piwik PRO. Here's what you need to do:

Log in to Piwik PRO.
Go to Menu > Administration.
Navigate to Sites & apps.
Click Add a site or app.
Type the app name and address, and click Save.
Set the time zone and currency.
Note the site/app ID. The ID is under the app name. Example: 00000000-0000-0000-0000-000000000000.
Note your tracking endpoint URL. This is the base URL where the SDK sends collected events. By default, this is the same as your Piwik PRO instance address (for example, https://example.piwik.pro). If your organization uses a custom tracking endpoint, check with your Piwik PRO administrator.

Install the library

To install the library with Flutter or Dart, follow these steps:

Run the following command:

$ flutter pub add flutter_piwikpro

$ dart pub add flutter_piwikpro

This adds the latest compatible version of flutter_piwikpro to your app's pubspec.yaml and automatically resolves its dependencies.
(Optional) Your editor might support dart pub get or flutter pub get. Check the docs for your editor to learn more.
Now in your Dart code, you can use the following method:

import 'package:flutter_piwikpro/flutter_piwikpro.dart';

iOS dependency managers

On iOS, flutter_piwikpro supports Swift Package Manager (SPM) and CocoaPods. SPM support is available in flutter_piwikpro 2.3.0 and later. Earlier versions use CocoaPods only.

Swift Package Manager

To use SPM with flutter_piwikpro, you need Flutter 3.41 or later and an iOS deployment target of 13.0 or later. Flutter 3.44 and later enable SPM by default.

After adding flutter_piwikpro to your app, run:

flutter run

Flutter automatically resolves the native Piwik PRO SDK dependency and registers the plugin. You don't need to manually add the SDK in Xcode, add the -ObjC linker flag, or change your Dart tracking code.

If the app's pubspec.yaml sets enable-swift-package-manager: false, remove that entry. This setting overrides your global Flutter configuration.

If you're using Flutter 3.41, or you previously disabled SPM globally, enable SPM with:

flutter config --enable-swift-package-manager

If another plugin in your app still requires CocoaPods, Flutter keeps using CocoaPods for that plugin.

To migrate an existing app, follow Flutter's SPM guide for app developers.

CocoaPods

You can continue using CocoaPods in existing apps.

To use CocoaPods with Flutter 3.44 or later, add the following configuration to the existing flutter section in the app's pubspec.yaml:

flutter:
  config:
    enable-swift-package-manager: false

If you're using Flutter older than 3.41 and enabled SPM globally, either upgrade Flutter or disable SPM to use CocoaPods:

flutter config --no-enable-swift-package-manager

Set up the tracker

To set up the Piwik PRO tracker, follow these steps:

Run the following command. Provide your tracking endpoint URL, which is the base URL where the SDK posts events, for example, (https://example.piwik.pro/) and the site/app ID (Where to find it?).

await FlutterPiwikPro.sharedInstance.configureTracker(baseURL: 'https://example.piwik.pro/', siteId: '01234567-89ab-cdef-0123-456789abcdef');

How to use our SDK

All SDK methods are asynchronous and can throw exceptions. For example, calling SDK methods before configuring the tracker results in an error. You can handle this error with a standard try-catch block. See the example below:

try {
    final result =
    await FlutterPiwikPro.sharedInstance.trackDownload('http://your.server.com/bonusmap2.zip');
    print(result);
} catch (exception) {
    //handle an exception
}

If a method call is successful, most methods return a string that describes the called method and the parameters used, unless stated otherwise. For example:

FlutterPiwikPro - configureTracker completed with parameters: baseURL: https://example.piwik.pro/, siteId: 01234567-89ab-cdef-0123-456789abcdef