Analytics-Flutter

Analytics-Flutter lets you add Segment analytics to your Flutter app.

Supported platforms

Analytics-Flutter supports these platforms:

• Android
• iOS
• MacOS
• Web

Some destination plugins may not support all platform functionality. Refer to individual platform SDKs for more details.

Getting started

To install Analytics-Flutter:

1. Add the core package as a dependency.

    flutter pub add segment_analytics
   

2. (Optional) Add any plugin that you need.

    flutter pub add segment_analytics_plugin_firebase
   

3. Import the library in your Dart code.

    import 'package:segment_analytics/client.dart';
   

4. Add permissions to AndroidManifest.xml. Add the line below between the `` tags.

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

Setting up the client

The Flutter SDK package exposes a method called createClient which you can use to create the Segment Analytics client. This central client manages all of the tracking events. Segment recommends that you add this as a property on your main app’s state class.

const writeKey = 'SEGMENT_API_KEY';
final analytics = createClient(Configuration(writeKey));

You must pass the writeKey.

These are the options you can apply to configure the client:

Upgrading from pilot

If you’ve been using Analytics-Flutter since the pilot phase, follow these steps to use the upgraded version of Analytics-Flutter as Segment renamed the package of the library from analytics to segment_analytics.

1. Remove the analytics package and use segment_analytics in your pubspec.yaml file.

    -   analytics:
    -     git:
    -       url: https://github.com/segmentio/analytics_flutter
    -       ref: main
    -       path: packages/core
    +   segment_analytics: ^1.0.1
   

2. Change the imports from package:analytics to package:segment_analytics in your dart files.

    - import 'package:analytics/client.dart';
    + import 'package:segment_analytics/client.dart';
   

Tracking methods

Once you’ve installed the Analytics-Flutter library, you can start collecting data through Segment’s tracking methods:

• Track
• Screen
• Identify
• Group

Track

The Track method is how you record any actions your users perform, along with any properties that describe the action.

Future track(String event: string, {Map<String, dynamic>? properties});

analytics.track("View Product", properties: {
  "productId": 123,
  "productName": "Striped trousers"
});

Screen

The Screen method lets you record whenever a user sees a screen in your mobile app, along with any properties about the screen.

Future screen(String name: string, {Map<String, dynamic>? properties});

analytics.screen("ScreenName", properties: {
  "productSlug": "example-product-123",
});

See how to set up automatic screen tracking.

Identify

The Identify method lets you tie a user to their actions and record traits about them. This includes a unique user ID and any optional traits you know about them like their email, name, address. The traits option can include any information you might want to tie to the user, but when using any of the reserved user traits, you should make sure to only use them for their intended meaning. All reserved traits are strongly typed by the UserTraits class. When you use traits not listed as a reserved user trait, these go under the custom property.

Future identify({String? userId, UserTraits? userTraits});

analytics.identify(userId: "testUserId", userTraits: UserTraits(
  username: "MisterWhiskers",
  email: "hello@test.com",
  custom: {
    "plan": "premium"
  }
);

Group

The Group method is how you associate an individual user with a group — whether it’s a company, organization, account, project, team. This includes a unique group ID and any optional group traits you know about them like the company name, industry, the number of employees. The traits option can include any information you might want to tie to the group, but when using any of the reserved group traits, you should make sure to only use them for their intended meaning. All reserved traits are strongly typed by the GroupTraits class. When you use traits not listed as a reserved user trait, these go under the custom property.

Future group(String groupId, {GroupTraits? groupTraits});

analytics.group("some-company", groupTraits: GroupTraits(
  name: 'Segment',
  custom: {
    "region": "UK"
  }
);

Utility methods

The Analytics-Flutter utility methods help you work with plugins from the analytics timeline. They include:

• Alias
• Reset
• Flush

Alias

The Alias method is used to merge two user identities, effectively connecting two sets of user data as one. This is an advanced method, but it’s required to manage user identities successfully in some of Segment’s destinations.

Future alias(String newUserId);

analytics.alias("user-123");

Reset

The Reset method clears the internal state of the library for the current user and group. This is useful for apps where users can log in and out with different identities over time.

Note: Each time you call reset, a new AnonymousId generates automatically.

void reset();

analytics.reset();

Flush

By default, the analytics send to the API after 30 seconds or when 20 items accumulate, whichever happens first, and whenever the app resumes if the user has closed the app with some events unsent. You can modify these values by the flushAt and flushInterval config options. You can also trigger a flush event manually.

Future flush();

analytics.flush();

Advanced cleanup

In case you need to reinitialize the client, because you called createClient more than once for the same client in your application lifecycle, use this method on the old client to clear any subscriptions and timers first.

var analytics = createClient(Configuration(writeKey));

analytics.cleanup();

analytics = createClient(Configuration(writeKey));

If you don’t do this, the old client instance still exists and retains the timers, which makes all of your events fire twice.

Automatic screen tracking

Automatic screen tracking enables you to track navigation globally, as sending a screen() event with each navigation action gets tiresome quickly. To set up automatic screen tracking, you need to add the analytics navigator observer to your app’s navigator observers. For example, if you’re using the MaterialApp class, add the following:

return MaterialApp(navigatorObservers: [
  ScreenObserver()
]);

Plugin architecture

Segment’s plugin architecture enables you to modify and augment how the analytics client works. You have complete control over how the events process before being uploaded to the Segment API. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done.

In order to customize what happens after an event is created, you can create and place various plugins along the processing pipeline that an event goes through. This pipeline is referred to as a timeline.

As plugins run through a timeline, they execute in order of insertion based on their entry types. Segment has these 5 entry types:

Plugins can have their own native code (for example, the iOS-only analytics_plugin_idfa) or wrap an underlying library (such as analytics_plugin_firebase which uses firebase_core and firebase_analytics under the hood).

Destination plugins

Segment is included as a DestinationPlugin out of the box. You can add as many destination plugins as you like and upload events and data to them.

You can pass autoAddSegmentDestination = false in the options when setting up your client to prevent the SegmentDestination plugin from being added automatically.

Adding Plugins

You can add a plugin at any time through the Add method.

import 'package:segment_analytics/client.dart';
import 'package:segment_analytics/event.dart';
import 'package:segment_analytics/state.dart';
import 'package:segment_analytics_plugin_advertising_id/plugin_advertising_id.dart';
import 'package:segment_analytics_plugin_idfa/plugin_idfa.dart';
import 'package:segment_analytics_plugin_firebase/plugin_firebase.dart'
    show FirebaseDestination;

const writeKey = 'SEGMENT_API_KEY';

class _MyAppState extends State<MyApp> {
  final analytics = createClient(Configuration(writeKey));

  @override
  void initState() {
    super.initState();
    initPlatformState();

    analytics
        .addPlugin(FirebaseDestination(DefaultFirebaseOptions.currentPlatform));
    analytics.addPlugin(PluginAdvertisingId());
    analytics.addPlugin(PluginIdfa());
  }
}

Writing your own plugins

Plugins are implemented by extending one of the provided plugin classes. The available plugin classes are:

• Plugin
• EventPlugin
• DestinationPlugin
• UtilityPlugin
• PlatformPlugin

Any plugin must be an extension of one of these classes.

You can then customize the functionality by overriding different methods on the base class. For example, here is a Logger plugin:

import 'dart:convert';

import 'package:segment_analytics/analytics.dart';
import 'package:segment_analytics/event.dart';
import 'package:segment_analytics/plugin.dart';
import 'package:segment_analytics/logger.dart';

class EventLogger extends DestinationPlugin {
  var logKind = LogFilterKind.debug;

  EventLogger() : super("event_logger");

  @override
  void configure(Analytics analytics) {
    pAnalytics = analytics;
  }

  @override
  Future<RawEvent?>? execute(RawEvent event) async {
    log("${event.type.toString().toUpperCase()} event${event is TrackEvent ? " (${event.event})" : ''} saved: \n${jsonEncode(event.toJson())}",
        kind: logKind);
    return event;
  }
}

As it overrides the execute method, this Logger calls log for every event going through the timeline.

Supported plugins

You can use these plugins to meet your tracking needs:

Controlling upload with flush policies

You can use FlushPolicies to more granularly control when events upload.

A flush policy defines the strategy for deciding when to flush. This can be on an interval, on a certain time of day, after receiving a certain number of events, or even after receiving a particular event. This gives you more flexibility on when to send events to Segment.

To make use of flush policies, you can set them in the configuration of the client:

import 'package:segment_analytics/flush_policies/count_flush_policy.dart';
import 'package:segment_analytics/flush_policies/timer_flush_policy.dart';

final analytics = createClient(Configuration(/*...*/, flushPolicies: [
  CountFlushPolicy(10),
  TimerFlushPolicy(100000)
]));

You can set several policies at a time. Whenever any policy decides it’s time for a flush, it triggers an upload of the events. The rest are reset so that their logic restarts after every flush.

This means only the first policy to reach shouldFlush gets to trigger a flush at a time. In the example above, when either the event count gets to 5 or the timer reaches 500ms, whatever comes first triggers a flush.

Segment has several standard FlushPolicies:

• CountFlushPolicy triggers whenever a certain number of events is reached.
• TimerFlushPolicy triggers on an interval of milliseconds.
• StartupFlushPolicy triggers on client startup only.

Adding or removing policies

One of the main advantanges of FlushPolicies is that you can add and remove policies whenever you want. This is powerful when you want to reduce or increase the amount of flushes.

For example, you might want to disable flushes if you detect the user has no network:

if (isConnected) {
  analytics.addFlushPolicy(policiesIfNetworkIsUp);
} else {
  analytics.removeFlushPolicy(policiesIfNetworkIsUp)
}

Creating your own flush policies

You can create a custom FlushPolicy for your application needs by implementing the FlushPolicy interface. You can also extend the FlushPolicyBase class that already creates and handles the shouldFlush value reset.

A FlushPolicy only needs to implement one method:

• onEvent(RawEvent event): Gets called on every event tracked by your client.

A FlushPolicy can optionally implement:

• reset(): Calls after a flush is triggered either by your policy, by another policy, or manually.
• start(): Executes when the flush policy is enabled and added to the client. This is a good place to start background operations, make async calls, and configure things before execution.

The FlushPolicy should have a shouldFlush boolean value. When this is set to true, the client attempts to upload events. Each policy should reset this value to false according to its own logic, although it’s pretty common to do it inside the reset method.

import 'package:segment_analytics/event.dart';
import 'package:segment_analytics/flush_policies/flush_policy.dart';

class FlushOnScreenEventsPolicy extends FlushPolicy {

  @override
  onEvent(RawEvent event) {
    // Only flush when a screen even happens
    if (event is ScreenEvent) {
      this.shouldFlush = true;
    }
  }

  @override
  reset() {
    // Superclass will reset the shouldFlush value so that the next screen event triggers a flush again
    // But you can also reset the value whenever, say another event comes in or after a timeout
    super.reset();
  }
}

Custom logging

By default, any logging is done through the standard Flutter logging mechanism. To customize logging, you can build your own logger, which must implement the LogTarget mixin. For example:

import 'package:segment_analytics/logger.dart';

void customDebugLog(String msg) {
  // ...
}

void customWarningLog(String msg) {
  // ...
}

void customErrorLog(String msg) {
  // ...
}

class CustomLogger with LogTarget {
  @override
  void parseLog(LogMessage log) {
    switch (log.kind) {
      case LogFilterKind.debug:
        customDebugLog("Segment: ${log.message}");
        break;
      case LogFilterKind.warning:
        customWarningLog("Segment: ${log.message}");
        break;
      case LogFilterKind.error:
        customErrorLog("Segment: ${log.message}");
        break;
    }
  }
}

// Set the default logger to use the CustomLogger
LogFactory.logger = CustomLogger();

Handling errors

You can handle analytics client errors through the errorHandler option.

The error handler configuration receives a function which gets called whenever an error happens on the analytics client. It receives an Exception that extends one of the errors from errors.dart.

You can use this error handling to trigger different behaviors in the client when a problem occurs. For example, if the client gets rate limited, you could use the error handler to swap flush policies to be less aggressive.

import 'package:segment_analytics/errors.dart';

//...

final flushPolicies = [CountFlushPolicy(5), TimerFlushPolicy(500)];

void errorHandler(Exception error) {
  if (error is NetworkServerLimited) {
    // Remove all flush policies
    analytics.removeFlushPolicy(analytics.getFlushPolicies());
    // Add less persistent flush policies
    analytics.addFlushPolicy([
      CountFlushPolicy(100),
      TimerFlushPolicy(5000)
    ]);
  }
}

final analytics = createClient(Configuration(writeKey),
  errorHandler: errorHandler,
  flushPolicies: flushPolicies);

Reporting errors from plugins

Plugins can also report errors to the handler by using the .error function of the analytics client. Segment recommends you to use the PluginError for consistency, and to attach the innerError with the actual exception that was hit.

import 'package:segment_analytics/errors.dart';

//...

try {
  distinctId = await mixpanel.getDistinctId();
} catch (e) {
  analytics.error(
    PluginError('Error: Mixpanel error calling getDistinctId', e)
  );
}

Platfom specific info

Web

analytics_flutter on web checks for Analytics.JS userInfo cookies/localStorage and reuses the anonymousId data.

LocalStorage recovery only works when running in the same domain/subdomain.

Example app

See the example app to check a full test app of how to integrate Analytics-Flutter into your own Flutter app.