Docs

Advanced usage

User ID

The user ID is an additional, optional non-empty unique string identifying the user (not set by default). It can be, for example, a unique username or user's email address. If the provided user ID is sent to the analytics part together with the visitor ID (which is always automatically generated by the SDK), it allows the association of events from various platforms (for example iOS and Android) to the same user provided that the same user ID is used on all platforms. You can read more about User ID here.

You can set a user ID using the setUserId method:

await FlutterPiwikPro.sharedInstance.setUserId('testUserId');
  • String id – any non-empty unique string identifying the user. Passing null will delete the current user ID.

User email address

The user email address is another string used for identifying users - a provided user email is sent to the audience manager part when you send the custom profile attribute configured on the audience manager web panel. Similarly to the user ID, it allows the association of data from various platforms (for example iOS and Android) to the same user as long as the same email is used on all platforms.

It is recommended to set the user email to track audience manager profile attributes as it will create a better user profile.

You can set a user email using the setUserEmail method:

await FlutterPiwikPro.sharedInstance.setUserEmail('[email protected]');
  • String email – a string representing an email address.

Visitor ID

SDK uses various IDs for tracking the user. The main one is visitor ID, which is internally randomly generated once by the SDK on the first usage and is then stored locally on the device. The visitor ID will never change unless the user removes the application from the device so that all events sent from his device will always be assigned to the same user in the Piwik PRO web panel. When the anonymization is enabled, a new visitor ID is generated each time the application is started. We recommend using userID instead of VisitorID.

Still, you can set a visitor ID using the setVisitorId method:

await FlutterPiwikPro.sharedInstance.setVisitorId('Id');
  • String id – a string containing a new Visitor ID.

You can also set the visitor ID from a deep link using the setVisitorIdFromDeepLink method. This allows linking a website visitor to an app visitor:

final bool ok = await FlutterPiwikPro.sharedInstance
    .setVisitorIdFromDeepLink('https://example.com?pk_vid=0123456789abcdef');

To configure the lifetime of the visitor ID, use setVisitorIDLifetime and getVisitorIDLifetime:

await FlutterPiwikPro.sharedInstance.setVisitorIDLifetime(30 * 24 * 60 * 60 * 1000);
final int lifetime = await FlutterPiwikPro.sharedInstance.getVisitorIDLifetime();

Setting session timeout

A session represents a set of user's interactions with your app. By default, Analytics is closing the session after 30 minutes of inactivity, counting from the last recorded event in session and when the user will open up the app again the new session is started. You can configure the tracker to automatically close the session when users have placed your app in the background for a period of time. That period is defined by the setSessionTimeout method.

await FlutterPiwikPro.sharedInstance.setSessionTimeout(1000);
  • int timeoutInMilliseconds – session timeout in milliseconds. Default: 1800000 (30 minutes).

Setting dispatch interval

All tracking events are saved locally and by default. They are automatically sent to the server every 30 seconds. You can change this interval using the setDispatchInterval method:

await FlutterPiwikPro.sharedInstance.setDispatchInterval(10000);
  • int intervalInMilliseconds – dispatch interval in milliseconds. Default: 30000.

You can also manually send all queued events to the server using the dispatch method:

await FlutterPiwikPro.sharedInstance.dispatch();

Default custom variables

The SDK, by default, automatically adds some information in custom variables about the device (index 1), system version (index 2) and app version (index 3). By default, this option is turned on.

In case you need to configure custom variables separately, turn off this option and see the section above about tracking custom variables.

You can disable this behavior using the setIncludeDefaultVariables method:

await FlutterPiwikPro.sharedInstance.setIncludeDefaultVariables(false);
  • bool shouldInclude – a boolean value that removes Default Variables when false.

Opt-out

You can disable all tracking in the application by using the opt-out feature. No events will be sent to the server if the opt-out is set. By default, opt-out is not set and events are tracked.

You can opt out of tracking using the optOut method:

await FlutterPiwikPro.sharedInstance.optOut(true);
  • bool shouldOptOut – a boolean value that disables all tracking in the app when set to true.

Dry run

The SDK provides a dryRun flag that, when set, prevents any data from being sent to Piwik. The dryRun flag should be set whenever you are testing or debugging an implementation and do not want test data to appear in your Piwik reports.

You can set the dry run flag using the dryRun method:

await FlutterPiwikPro.sharedInstance.dryRun(true);
  • bool shouldDryRun – a boolean value that prevents any data being sent to a tracker when set to true.

Updated 4 days ago